clang/Serialization/ModuleFileExtension.h

0001 //===-- ModuleFileExtension.h - Module File Extensions ----------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLVM_CLANG_SERIALIZATION_MODULEFILEEXTENSION_H
0010 #define LLVM_CLANG_SERIALIZATION_MODULEFILEEXTENSION_H
0011
0012 #include "llvm/Support/ExtensibleRTTI.h"
0013 #include "llvm/Support/HashBuilder.h"
0014 #include "llvm/Support/MD5.h"
0015 #include <memory>
0016 #include <string>
0017
0018 namespace llvm {
0019 class BitstreamCursor;
0020 class BitstreamWriter;
0021 class raw_ostream;
0022 }
0023
0024 namespace clang {
0025
0026 class ASTReader;
0027 class ASTWriter;
0028 class Sema;
0029
0030 namespace serialization {
0031   class ModuleFile;
0032 } // end namespace serialization
0033
0034 /// Metadata for a module file extension.
0035 struct ModuleFileExtensionMetadata {
0036   /// The name used to identify this particular extension block within
0037   /// the resulting module file. It should be unique to the particular
0038   /// extension, because this name will be used to match the name of
0039   /// an extension block to the appropriate reader.
0040   std::string BlockName;
0041
0042   /// The major version of the extension data.
0043   unsigned MajorVersion;
0044
0045   /// The minor version of the extension data.
0046   unsigned MinorVersion;
0047
0048   /// A string containing additional user information that will be
0049   /// stored with the metadata.
0050   std::string UserInfo;
0051 };
0052
0053 class ModuleFileExtensionReader;
0054 class ModuleFileExtensionWriter;
0055
0056 /// An abstract superclass that describes a custom extension to the
0057 /// module/precompiled header file format.
0058 ///
0059 /// A module file extension can introduce additional information into
0060 /// compiled module files (.pcm) and precompiled headers (.pch) via a
0061 /// custom writer that can then be accessed via a custom reader when
0062 /// the module file or precompiled header is loaded.
0063 ///
0064 /// Subclasses must use LLVM RTTI for open class hierarchies.
0065 class ModuleFileExtension
0066     : public llvm::RTTIExtends<ModuleFileExtension, llvm::RTTIRoot> {
0067 public:
0068   /// Discriminator for LLVM RTTI.
0069   static char ID;
0070
0071   virtual ~ModuleFileExtension();
0072
0073   /// Retrieves the metadata for this module file extension.
0074   virtual ModuleFileExtensionMetadata getExtensionMetadata() const = 0;
0075
0076   /// Hash information about the presence of this extension into the
0077   /// module hash.
0078   ///
0079   /// The module hash is used to distinguish different variants of a module that
0080   /// are incompatible. If the presence, absence, or version of the module file
0081   /// extension should force the creation of a separate set of module files,
0082   /// override this method to combine that distinguishing information into the
0083   /// module hash.
0084   ///
0085   /// The default implementation of this function simply does nothing, so the
0086   /// presence/absence of this extension does not distinguish module files.
0087   using ExtensionHashBuilder =
0088       llvm::HashBuilder<llvm::MD5, llvm::endianness::native>;
0089   virtual void hashExtension(ExtensionHashBuilder &HBuilder) const;
0090
0091   /// Create a new module file extension writer, which will be
0092   /// responsible for writing the extension contents into a particular
0093   /// module file.
0094   virtual std::unique_ptr<ModuleFileExtensionWriter>
0095   createExtensionWriter(ASTWriter &Writer) = 0;
0096
0097   /// Create a new module file extension reader, given the
0098   /// metadata read from the block and the cursor into the extension
0099   /// block.
0100   ///
0101   /// May return null to indicate that an extension block with the
0102   /// given metadata cannot be read.
0103   virtual std::unique_ptr<ModuleFileExtensionReader>
0104   createExtensionReader(const ModuleFileExtensionMetadata &Metadata,
0105                         ASTReader &Reader, serialization::ModuleFile &Mod,
0106                         const llvm::BitstreamCursor &Stream) = 0;
0107 };
0108
0109 /// Abstract base class that writes a module file extension block into
0110 /// a module file.
0111 class ModuleFileExtensionWriter {
0112   ModuleFileExtension *Extension;
0113
0114 protected:
0115   ModuleFileExtensionWriter(ModuleFileExtension *Extension)
0116     : Extension(Extension) { }
0117
0118 public:
0119   virtual ~ModuleFileExtensionWriter();
0120
0121   /// Retrieve the module file extension with which this writer is
0122   /// associated.
0123   ModuleFileExtension *getExtension() const { return Extension; }
0124
0125   /// Write the contents of the extension block into the given bitstream.
0126   ///
0127   /// Responsible for writing the contents of the extension into the
0128   /// given stream. All of the contents should be written into custom
0129   /// records with IDs >= FIRST_EXTENSION_RECORD_ID.
0130   virtual void writeExtensionContents(Sema &SemaRef,
0131                                       llvm::BitstreamWriter &Stream) = 0;
0132 };
0133
0134 /// Abstract base class that reads a module file extension block from
0135 /// a module file.
0136 ///
0137 /// Subclasses
0138 class ModuleFileExtensionReader {
0139   ModuleFileExtension *Extension;
0140
0141 protected:
0142   ModuleFileExtensionReader(ModuleFileExtension *Extension)
0143     : Extension(Extension) { }
0144
0145 public:
0146   /// Retrieve the module file extension with which this reader is
0147   /// associated.
0148   ModuleFileExtension *getExtension() const { return Extension; }
0149
0150   virtual ~ModuleFileExtensionReader();
0151 };
0152
0153 } // end namespace clang
0154
0155 #endif // LLVM_CLANG_SERIALIZATION_MODULEFILEEXTENSION_H