granicus.if.org Git - clang/blob - include/clang/AST/ExternalASTSource.h

   1 //===--- ExternalASTSource.h - Abstract External AST Interface --*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 //  This file defines the ExternalASTSource interface, which enables
  11 //  construction of AST nodes from some external source.x
  12 //
  13 //===----------------------------------------------------------------------===//
  14 #ifndef LLVM_CLANG_AST_EXTERNAL_AST_SOURCE_H
  15 #define LLVM_CLANG_AST_EXTERNAL_AST_SOURCE_H
  16
  17 #include "clang/AST/DeclarationName.h"
  18 #include "clang/AST/Type.h"
  19 #include "llvm/ADT/SmallVector.h"
  20 #include <cassert>
  21 #include <vector>
  22 namespace clang {
  23
  24 class ASTConsumer;
  25 class Decl;
  26 class DeclContext;
  27 class ExternalSemaSource; // layering violation required for downcasting
  28 class Stmt;
  29
  30 /// \brief Abstract interface for external sources of AST nodes.
  31 ///
  32 /// External AST sources provide AST nodes constructed from some
  33 /// external source, such as a precompiled header. External AST
  34 /// sources can resolve types and declarations from abstract IDs into
  35 /// actual type and declaration nodes, and read parts of declaration
  36 /// contexts.
  37 class ExternalASTSource {
  38   /// \brief Whether this AST source also provides information for
  39   /// semantic analysis.
  40   bool SemaSource;
  41
  42   friend class ExternalSemaSource;
  43
  44 public:
  45   ExternalASTSource() : SemaSource(false) { }
  46
  47   virtual ~ExternalASTSource();
  48
  49   /// \brief RAII class for safely pairing a StartedDeserializing call
  50   /// with FinishedDeserializing.
  51   class Deserializing {
  52     ExternalASTSource *Source;
  53   public:
  54     explicit Deserializing(ExternalASTSource *source) : Source(source) {
  55       assert(Source);
  56       Source->StartedDeserializing();
  57     }
  58     ~Deserializing() {
  59       Source->FinishedDeserializing();
  60     }
  61   };
  62
  63   /// \brief Resolve a declaration ID into a declaration, potentially
  64   /// building a new declaration.
  65   ///
  66   /// This method only needs to be implemented if the AST source ever
  67   /// passes back decl sets as VisibleDeclaration objects.
  68   virtual Decl *GetExternalDecl(uint32_t ID) = 0;
  69
  70   /// \brief Resolve a selector ID into a selector.
  71   ///
  72   /// This operation only needs to be implemented if the AST source
  73   /// returns non-zero for GetNumKnownSelectors().
  74   virtual Selector GetExternalSelector(uint32_t ID) = 0;
  75
  76   /// \brief Returns the number of selectors known to the external AST
  77   /// source.
  78   virtual uint32_t GetNumExternalSelectors() = 0;
  79
  80   /// \brief Resolve the offset of a statement in the decl stream into
  81   /// a statement.
  82   ///
  83   /// This operation is meant to be used via a LazyOffsetPtr.  It only
  84   /// needs to be implemented if the AST source uses methods like
  85   /// FunctionDecl::setLazyBody when building decls.
  86   virtual Stmt *GetExternalDeclStmt(uint64_t Offset) = 0;
  87
  88   /// \brief Finds all declarations with the given name in the
  89   /// given context.
  90   ///
  91   /// Generally the final step of this method is either to call
  92   /// SetExternalVisibleDeclsForName or to recursively call lookup on
  93   /// the DeclContext after calling SetExternalVisibleDecls.
  94   virtual DeclContext::lookup_result
  95   FindExternalVisibleDeclsByName(const DeclContext *DC,
  96                                  DeclarationName Name) = 0;
  97
  98   /// \brief Deserialize all the visible declarations from external storage.
  99   ///
 100   /// Name lookup deserializes visible declarations lazily, thus a DeclContext
 101   /// may not have a complete name lookup table. This function deserializes
 102   /// the rest of visible declarations from the external storage and completes
 103   /// the name lookup table of the DeclContext.
 104   virtual void MaterializeVisibleDecls(const DeclContext *DC) = 0;
 105
 106   /// \brief Finds all declarations lexically contained within the given
 107   /// DeclContext.
 108   ///
 109   /// \return true if an error occurred
 110   virtual bool FindExternalLexicalDecls(const DeclContext *DC,
 111                                 llvm::SmallVectorImpl<Decl*> &Result) = 0;
 112
 113   /// \brief Notify ExternalASTSource that we started deserialization of
 114   /// a decl or type so until FinishedDeserializing is called there may be
 115   /// decls that are initializing. Must be paired with FinishedDeserializing.
 116   ///
 117   /// The default implementation of this method is a no-op.
 118   virtual void StartedDeserializing() { }
 119
 120   /// \brief Notify ExternalASTSource that we finished the deserialization of
 121   /// a decl or type. Must be paired with StartedDeserializing.
 122   ///
 123   /// The default implementation of this method is a no-op.
 124   virtual void FinishedDeserializing() { }
 125
 126   /// \brief Function that will be invoked when we begin parsing a new
 127   /// translation unit involving this external AST source.
 128   ///
 129   /// The default implementation of this method is a no-op.
 130   virtual void StartTranslationUnit(ASTConsumer *Consumer) { }
 131
 132   /// \brief Print any statistics that have been gathered regarding
 133   /// the external AST source.
 134   ///
 135   /// The default implementation of this method is a no-op.
 136   virtual void PrintStats();
 137
 138 protected:
 139   static DeclContext::lookup_result
 140   SetExternalVisibleDeclsForName(const DeclContext *DC,
 141                                  DeclarationName Name,
 142                                  llvm::SmallVectorImpl<NamedDecl*> &Decls);
 143
 144   static DeclContext::lookup_result
 145   SetNoExternalVisibleDeclsForName(const DeclContext *DC,
 146                                    DeclarationName Name);
 147
 148   void MaterializeVisibleDeclsForName(const DeclContext *DC,
 149                                  DeclarationName Name,
 150                                  llvm::SmallVectorImpl<NamedDecl*> &Decls);
 151 };
 152
 153 /// \brief A lazy pointer to an AST node (of base type T) that resides
 154 /// within an external AST source.
 155 ///
 156 /// The AST node is identified within the external AST source by a
 157 /// 63-bit offset, and can be retrieved via an operation on the
 158 /// external AST source itself.
 159 template<typename T, typename OffsT, T* (ExternalASTSource::*Get)(OffsT Offset)>
 160 struct LazyOffsetPtr {
 161   /// \brief Either a pointer to an AST node or the offset within the
 162   /// external AST source where the AST node can be found.
 163   ///
 164   /// If the low bit is clear, a pointer to the AST node. If the low
 165   /// bit is set, the upper 63 bits are the offset.
 166   mutable uint64_t Ptr;
 167
 168 public:
 169   LazyOffsetPtr() : Ptr(0) { }
 170
 171   explicit LazyOffsetPtr(T *Ptr) : Ptr(reinterpret_cast<uint64_t>(Ptr)) { }
 172   explicit LazyOffsetPtr(uint64_t Offset) : Ptr((Offset << 1) | 0x01) {
 173     assert((Offset << 1 >> 1) == Offset && "Offsets must require < 63 bits");
 174     if (Offset == 0)
 175       Ptr = 0;
 176   }
 177
 178   LazyOffsetPtr &operator=(T *Ptr) {
 179     this->Ptr = reinterpret_cast<uint64_t>(Ptr);
 180     return *this;
 181   }
 182
 183   LazyOffsetPtr &operator=(uint64_t Offset) {
 184     assert((Offset << 1 >> 1) == Offset && "Offsets must require < 63 bits");
 185     if (Offset == 0)
 186       Ptr = 0;
 187     else
 188       Ptr = (Offset << 1) | 0x01;
 189
 190     return *this;
 191   }
 192
 193   /// \brief Whether this pointer is non-NULL.
 194   ///
 195   /// This operation does not require the AST node to be deserialized.
 196   operator bool() const { return Ptr != 0; }
 197
 198   /// \brief Whether this pointer is currently stored as an offset.
 199   bool isOffset() const { return Ptr & 0x01; }
 200
 201   /// \brief Retrieve the pointer to the AST node that this lazy pointer
 202   ///
 203   /// \param Source the external AST source.
 204   ///
 205   /// \returns a pointer to the AST node.
 206   T* get(ExternalASTSource *Source) const {
 207     if (isOffset()) {
 208       assert(Source &&
 209              "Cannot deserialize a lazy pointer without an AST source");
 210       Ptr = reinterpret_cast<uint64_t>((Source->*Get)(Ptr >> 1));
 211     }
 212     return reinterpret_cast<T*>(Ptr);
 213   }
 214 };
 215
 216 /// \brief A lazy pointer to a statement.
 217 typedef LazyOffsetPtr<Stmt, uint64_t, &ExternalASTSource::GetExternalDeclStmt>
 218   LazyDeclStmtPtr;
 219
 220 /// \brief A lazy pointer to a declaration.
 221 typedef LazyOffsetPtr<Decl, uint32_t, &ExternalASTSource::GetExternalDecl>
 222   LazyDeclPtr;
 223
 224 } // end namespace clang
 225
 226 #endif // LLVM_CLANG_AST_EXTERNAL_AST_SOURCE_H