ASTUnit.h revision 389db16c63eec6ecfa9b235155252d8da766e94e 
1//===--- ASTUnit.h - ASTUnit utility ----------------------------*- 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// ASTUnit utility class.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_CLANG_FRONTEND_ASTUNIT_H
15#define LLVM_CLANG_FRONTEND_ASTUNIT_H
16
17#include "clang/Index/ASTLocation.h"
18#include "clang/Serialization/ASTBitCodes.h"
19#include "clang/Sema/Sema.h"
20#include "clang/Sema/CodeCompleteConsumer.h"
21#include "clang/Lex/PreprocessingRecord.h"
22#include "clang/Basic/SourceManager.h"
23#include "clang/Basic/FileManager.h"
24#include "clang/Basic/FileSystemOptions.h"
25#include "clang-c/Index.h"
26#include "llvm/ADT/IntrusiveRefCntPtr.h"
27#include "llvm/ADT/OwningPtr.h"
28#include "llvm/ADT/SmallVector.h"
29#include "llvm/ADT/StringMap.h"
30#include "llvm/System/Path.h"
31#include <map>
32#include <string>
33#include <vector>
34#include <cassert>
35#include <utility>
36#include <sys/types.h>
37
38namespace llvm {
39  class MemoryBuffer;
40}
41
42namespace clang {
43class ASTContext;
44class CodeCompleteConsumer;
45class CompilerInvocation;
46class Decl;
47class Diagnostic;
48class FileEntry;
49class FileManager;
50class HeaderSearch;
51class Preprocessor;
52class SourceManager;
53class TargetInfo;
54
55using namespace idx;
56
57/// \brief Utility class for loading a ASTContext from an AST file.
58///
59class ASTUnit {
60public:
61  typedef std::map<FileID, std::vector<PreprocessedEntity *> >
62    PreprocessedEntitiesByFileMap;
63
64private:
65  llvm::IntrusiveRefCntPtr<Diagnostic> Diagnostics;
66  llvm::OwningPtr<FileManager>      FileMgr;
67  llvm::OwningPtr<SourceManager>    SourceMgr;
68  llvm::OwningPtr<HeaderSearch>     HeaderInfo;
69  llvm::OwningPtr<TargetInfo>       Target;
70  llvm::OwningPtr<Preprocessor>     PP;
71  llvm::OwningPtr<ASTContext>       Ctx;
72
73  FileSystemOptions FileSystemOpts;
74
75  /// \brief The AST consumer that received information about the translation
76  /// unit as it was parsed or loaded.
77  llvm::OwningPtr<ASTConsumer> Consumer;
78
79  /// \brief The semantic analysis object used to type-check the translation
80  /// unit.
81  llvm::OwningPtr<Sema> TheSema;
82
83  /// Optional owned invocation, just used to make the invocation used in
84  /// LoadFromCommandLine available.
85  llvm::OwningPtr<CompilerInvocation> Invocation;
86
87  // OnlyLocalDecls - when true, walking this AST should only visit declarations
88  // that come from the AST itself, not from included precompiled headers.
89  // FIXME: This is temporary; eventually, CIndex will always do this.
90  bool                              OnlyLocalDecls;
91
92  /// \brief Whether to capture any diagnostics produced.
93  bool CaptureDiagnostics;
94
95  /// \brief Track whether the main file was loaded from an AST or not.
96  bool MainFileIsAST;
97
98  /// \brief Whether this AST represents a complete translation unit.
99  bool CompleteTranslationUnit;
100
101  /// \brief Whether we should time each operation.
102  bool WantTiming;
103
104  /// Track the top-level decls which appeared in an ASTUnit which was loaded
105  /// from a source file.
106  //
107  // FIXME: This is just an optimization hack to avoid deserializing large parts
108  // of a PCH file when using the Index library on an ASTUnit loaded from
109  // source. In the long term we should make the Index library use efficient and
110  // more scalable search mechanisms.
111  std::vector<Decl*> TopLevelDecls;
112
113  /// The name of the original source file used to generate this ASTUnit.
114  std::string OriginalSourceFile;
115
116  // Critical optimization when using clang_getCursor().
117  ASTLocation LastLoc;
118
119  /// \brief The set of diagnostics produced when creating this
120  /// translation unit.
121  llvm::SmallVector<StoredDiagnostic, 4> StoredDiagnostics;
122
123  /// \brief The number of stored diagnostics that come from the driver
124  /// itself.
125  ///
126  /// Diagnostics that come from the driver are retained from one parse to
127  /// the next.
128  unsigned NumStoredDiagnosticsFromDriver;
129
130  /// \brief Temporary files that should be removed when the ASTUnit is
131  /// destroyed.
132  llvm::SmallVector<llvm::sys::Path, 4> TemporaryFiles;
133
134  /// \brief A mapping from file IDs to the set of preprocessed entities
135  /// stored in that file.
136  ///
137  /// FIXME: This is just an optimization hack to avoid searching through
138  /// many preprocessed entities during cursor traversal in the CIndex library.
139  /// Ideally, we would just be able to perform a binary search within the
140  /// list of preprocessed entities.
141  PreprocessedEntitiesByFileMap PreprocessedEntitiesByFile;
142
143  /// \brief Simple hack to allow us to assert that ASTUnit is not being
144  /// used concurrently, which is not supported.
145  ///
146  /// Clients should create instances of the ConcurrencyCheck class whenever
147  /// using the ASTUnit in a way that isn't intended to be concurrent, which is
148  /// just about any usage.
149  unsigned int ConcurrencyCheckValue;
150  static const unsigned int CheckLocked = 28573289;
151  static const unsigned int CheckUnlocked = 9803453;
152
153  /// \brief Counter that determines when we want to try building a
154  /// precompiled preamble.
155  ///
156  /// If zero, we will never build a precompiled preamble. Otherwise,
157  /// it's treated as a counter that decrements each time we reparse
158  /// without the benefit of a precompiled preamble. When it hits 1,
159  /// we'll attempt to rebuild the precompiled header. This way, if
160  /// building the precompiled preamble fails, we won't try again for
161  /// some number of calls.
162  unsigned PreambleRebuildCounter;
163
164  /// \brief The file in which the precompiled preamble is stored.
165  std::string PreambleFile;
166
167  /// \brief The contents of the preamble that has been precompiled to
168  /// \c PreambleFile.
169  std::vector<char> Preamble;
170
171  /// \brief Whether the preamble ends at the start of a new line.
172  ///
173  /// Used to inform the lexer as to whether it's starting at the beginning of
174  /// a line after skipping the preamble.
175  bool PreambleEndsAtStartOfLine;
176
177  /// \brief The size of the source buffer that we've reserved for the main
178  /// file within the precompiled preamble.
179  unsigned PreambleReservedSize;
180
181  /// \brief Keeps track of the files that were used when computing the
182  /// preamble, with both their buffer size and their modification time.
183  ///
184  /// If any of the files have changed from one compile to the next,
185  /// the preamble must be thrown away.
186  llvm::StringMap<std::pair<off_t, time_t> > FilesInPreamble;
187
188  /// \brief When non-NULL, this is the buffer used to store the contents of
189  /// the main file when it has been padded for use with the precompiled
190  /// preamble.
191  llvm::MemoryBuffer *SavedMainFileBuffer;
192
193  /// \brief When non-NULL, this is the buffer used to store the
194  /// contents of the preamble when it has been padded to build the
195  /// precompiled preamble.
196  llvm::MemoryBuffer *PreambleBuffer;
197
198  /// \brief The number of warnings that occurred while parsing the preamble.
199  ///
200  /// This value will be used to restore the state of the \c Diagnostic object
201  /// when re-using the precompiled preamble. Note that only the
202  /// number of warnings matters, since we will not save the preamble
203  /// when any errors are present.
204  unsigned NumWarningsInPreamble;
205
206  /// \brief The number of diagnostics that were stored when parsing
207  /// the precompiled preamble.
208  ///
209  /// This value is used to determine how many of the stored
210  /// diagnostics should be retained when reparsing in the presence of
211  /// a precompiled preamble.
212  unsigned NumStoredDiagnosticsInPreamble;
213
214  /// \brief A list of the serialization ID numbers for each of the top-level
215  /// declarations parsed within the precompiled preamble.
216  std::vector<serialization::DeclID> TopLevelDeclsInPreamble;
217
218  /// \brief Whether we should be caching code-completion results.
219  bool ShouldCacheCodeCompletionResults;
220
221public:
222  /// \brief A cached code-completion result, which may be introduced in one of
223  /// many different contexts.
224  struct CachedCodeCompletionResult {
225    /// \brief The code-completion string corresponding to this completion
226    /// result.
227    CodeCompletionString *Completion;
228
229    /// \brief A bitmask that indicates which code-completion contexts should
230    /// contain this completion result.
231    ///
232    /// The bits in the bitmask correspond to the values of
233    /// CodeCompleteContext::Kind. To map from a completion context kind to a
234    /// bit, subtract one from the completion context kind and shift 1 by that
235    /// number of bits. Many completions can occur in several different
236    /// contexts.
237    unsigned ShowInContexts;
238
239    /// \brief The priority given to this code-completion result.
240    unsigned Priority;
241
242    /// \brief The libclang cursor kind corresponding to this code-completion
243    /// result.
244    CXCursorKind Kind;
245
246    /// \brief The availability of this code-completion result.
247    CXAvailabilityKind Availability;
248
249    /// \brief The simplified type class for a non-macro completion result.
250    SimplifiedTypeClass TypeClass;
251
252    /// \brief The type of a non-macro completion result, stored as a unique
253    /// integer used by the string map of cached completion types.
254    ///
255    /// This value will be zero if the type is not known, or a unique value
256    /// determined by the formatted type string. Se \c CachedCompletionTypes
257    /// for more information.
258    unsigned Type;
259  };
260
261  /// \brief Retrieve the mapping from formatted type names to unique type
262  /// identifiers.
263  llvm::StringMap<unsigned> &getCachedCompletionTypes() {
264    return CachedCompletionTypes;
265  }
266
267private:
268  /// \brief The set of cached code-completion results.
269  std::vector<CachedCodeCompletionResult> CachedCompletionResults;
270
271  /// \brief A mapping from the formatted type name to a unique number for that
272  /// type, which is used for type equality comparisons.
273  llvm::StringMap<unsigned> CachedCompletionTypes;
274
275  /// \brief The number of top-level declarations present the last time we
276  /// cached code-completion results.
277  ///
278  /// The value is used to help detect when we should repopulate the global
279  /// completion cache.
280  unsigned NumTopLevelDeclsAtLastCompletionCache;
281
282  /// \brief The number of reparses left until we'll consider updating the
283  /// code-completion cache.
284  ///
285  /// This is meant to avoid thrashing during reparsing, by not allowing the
286  /// code-completion cache to be updated on every reparse.
287  unsigned CacheCodeCompletionCoolDown;
288
289  /// \brief Bit used by CIndex to mark when a translation unit may be in an
290  /// inconsistent state, and is not safe to free.
291  unsigned UnsafeToFree : 1;
292
293  /// \brief Cache any "global" code-completion results, so that we can avoid
294  /// recomputing them with each completion.
295  void CacheCodeCompletionResults();
296
297  /// \brief Clear out and deallocate
298  void ClearCachedCompletionResults();
299
300  ASTUnit(const ASTUnit&); // DO NOT IMPLEMENT
301  ASTUnit &operator=(const ASTUnit &); // DO NOT IMPLEMENT
302
303  explicit ASTUnit(bool MainFileIsAST);
304
305  void CleanTemporaryFiles();
306  bool Parse(llvm::MemoryBuffer *OverrideMainBuffer);
307
308  std::pair<llvm::MemoryBuffer *, std::pair<unsigned, bool> >
309  ComputePreamble(CompilerInvocation &Invocation,
310                  unsigned MaxLines, bool &CreatedBuffer);
311
312  llvm::MemoryBuffer *getMainBufferWithPrecompiledPreamble(
313                                         CompilerInvocation PreambleInvocation,
314                                                     bool AllowRebuild = true,
315                                                        unsigned MaxLines = 0);
316  void RealizeTopLevelDeclsFromPreamble();
317
318public:
319  class ConcurrencyCheck {
320    volatile ASTUnit &Self;
321
322  public:
323    explicit ConcurrencyCheck(ASTUnit &Self)
324      : Self(Self)
325    {
326      assert(Self.ConcurrencyCheckValue == CheckUnlocked &&
327             "Concurrent access to ASTUnit!");
328      Self.ConcurrencyCheckValue = CheckLocked;
329    }
330
331    ~ConcurrencyCheck() {
332      Self.ConcurrencyCheckValue = CheckUnlocked;
333    }
334  };
335  friend class ConcurrencyCheck;
336
337  ~ASTUnit();
338
339  bool isMainFileAST() const { return MainFileIsAST; }
340
341  bool isUnsafeToFree() const { return UnsafeToFree; }
342  void setUnsafeToFree(bool Value) { UnsafeToFree = Value; }
343
344  const Diagnostic &getDiagnostics() const { return *Diagnostics; }
345  Diagnostic &getDiagnostics()             { return *Diagnostics; }
346
347  const SourceManager &getSourceManager() const { return *SourceMgr; }
348        SourceManager &getSourceManager()       { return *SourceMgr; }
349
350  const Preprocessor &getPreprocessor() const { return *PP.get(); }
351        Preprocessor &getPreprocessor()       { return *PP.get(); }
352
353  const ASTContext &getASTContext() const { return *Ctx.get(); }
354        ASTContext &getASTContext()       { return *Ctx.get(); }
355
356  bool hasSema() const { return TheSema; }
357  Sema &getSema() const {
358    assert(TheSema && "ASTUnit does not have a Sema object!");
359    return *TheSema;
360  }
361
362  const FileManager &getFileManager() const { return *FileMgr; }
363        FileManager &getFileManager()       { return *FileMgr; }
364
365  const FileSystemOptions &getFileSystemOpts() const { return FileSystemOpts; }
366
367  const std::string &getOriginalSourceFileName();
368  const std::string &getASTFileName();
369
370  /// \brief Add a temporary file that the ASTUnit depends on.
371  ///
372  /// This file will be erased when the ASTUnit is destroyed.
373  void addTemporaryFile(const llvm::sys::Path &TempFile) {
374    TemporaryFiles.push_back(TempFile);
375  }
376
377  bool getOnlyLocalDecls() const { return OnlyLocalDecls; }
378
379  /// \brief Retrieve the maximum PCH level of declarations that a
380  /// traversal of the translation unit should consider.
381  unsigned getMaxPCHLevel() const;
382
383  void setLastASTLocation(ASTLocation ALoc) { LastLoc = ALoc; }
384  ASTLocation getLastASTLocation() const { return LastLoc; }
385
386
387  llvm::StringRef getMainFileName() const;
388
389  typedef std::vector<Decl *>::iterator top_level_iterator;
390
391  top_level_iterator top_level_begin() {
392    assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
393    if (!TopLevelDeclsInPreamble.empty())
394      RealizeTopLevelDeclsFromPreamble();
395    return TopLevelDecls.begin();
396  }
397
398  top_level_iterator top_level_end() {
399    assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
400    if (!TopLevelDeclsInPreamble.empty())
401      RealizeTopLevelDeclsFromPreamble();
402    return TopLevelDecls.end();
403  }
404
405  std::size_t top_level_size() const {
406    assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
407    return TopLevelDeclsInPreamble.size() + TopLevelDecls.size();
408  }
409
410  bool top_level_empty() const {
411    assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
412    return TopLevelDeclsInPreamble.empty() && TopLevelDecls.empty();
413  }
414
415  /// \brief Add a new top-level declaration.
416  void addTopLevelDecl(Decl *D) {
417    TopLevelDecls.push_back(D);
418  }
419
420  /// \brief Add a new top-level declaration, identified by its ID in
421  /// the precompiled preamble.
422  void addTopLevelDeclFromPreamble(serialization::DeclID D) {
423    TopLevelDeclsInPreamble.push_back(D);
424  }
425
426  /// \brief Retrieve the mapping from File IDs to the preprocessed entities
427  /// within that file.
428  PreprocessedEntitiesByFileMap &getPreprocessedEntitiesByFile() {
429    return PreprocessedEntitiesByFile;
430  }
431
432  // Retrieve the diagnostics associated with this AST
433  typedef const StoredDiagnostic *stored_diag_iterator;
434  stored_diag_iterator stored_diag_begin() const {
435    return StoredDiagnostics.begin();
436  }
437  stored_diag_iterator stored_diag_end() const {
438    return StoredDiagnostics.end();
439  }
440  unsigned stored_diag_size() const { return StoredDiagnostics.size(); }
441
442  llvm::SmallVector<StoredDiagnostic, 4> &getStoredDiagnostics() {
443    return StoredDiagnostics;
444  }
445
446  typedef std::vector<CachedCodeCompletionResult>::iterator
447    cached_completion_iterator;
448
449  cached_completion_iterator cached_completion_begin() {
450    return CachedCompletionResults.begin();
451  }
452
453  cached_completion_iterator cached_completion_end() {
454    return CachedCompletionResults.end();
455  }
456
457  unsigned cached_completion_size() const {
458    return CachedCompletionResults.size();
459  }
460
461  llvm::MemoryBuffer *getBufferForFile(llvm::StringRef Filename,
462                                       std::string *ErrorStr = 0,
463                                       int64_t FileSize = -1,
464                                       struct stat *FileInfo = 0);
465
466  /// \brief Whether this AST represents a complete translation unit.
467  ///
468  /// If false, this AST is only a partial translation unit, e.g., one
469  /// that might still be used as a precompiled header or preamble.
470  bool isCompleteTranslationUnit() const { return CompleteTranslationUnit; }
471
472  /// \brief A mapping from a file name to the memory buffer that stores the
473  /// remapped contents of that file.
474  typedef std::pair<std::string, const llvm::MemoryBuffer *> RemappedFile;
475
476  /// \brief Create a ASTUnit from an AST file.
477  ///
478  /// \param Filename - The AST file to load.
479  ///
480  /// \param Diags - The diagnostics engine to use for reporting errors; its
481  /// lifetime is expected to extend past that of the returned ASTUnit.
482  ///
483  /// \returns - The initialized ASTUnit or null if the AST failed to load.
484  static ASTUnit *LoadFromASTFile(const std::string &Filename,
485                                  llvm::IntrusiveRefCntPtr<Diagnostic> Diags,
486                                  const FileSystemOptions &FileSystemOpts,
487                                  bool OnlyLocalDecls = false,
488                                  RemappedFile *RemappedFiles = 0,
489                                  unsigned NumRemappedFiles = 0,
490                                  bool CaptureDiagnostics = false);
491
492private:
493  /// \brief Helper function for \c LoadFromCompilerInvocation() and
494  /// \c LoadFromCommandLine(), which loads an AST from a compiler invocation.
495  ///
496  /// \param PrecompilePreamble Whether to precompile the preamble of this
497  /// translation unit, to improve the performance of reparsing.
498  ///
499  /// \returns \c true if a catastrophic failure occurred (which means that the
500  /// \c ASTUnit itself is invalid), or \c false otherwise.
501  bool LoadFromCompilerInvocation(bool PrecompilePreamble);
502
503public:
504
505  /// LoadFromCompilerInvocation - Create an ASTUnit from a source file, via a
506  /// CompilerInvocation object.
507  ///
508  /// \param CI - The compiler invocation to use; it must have exactly one input
509  /// source file. The ASTUnit takes ownership of the CompilerInvocation object.
510  ///
511  /// \param Diags - The diagnostics engine to use for reporting errors; its
512  /// lifetime is expected to extend past that of the returned ASTUnit.
513  //
514  // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
515  // shouldn't need to specify them at construction time.
516  static ASTUnit *LoadFromCompilerInvocation(CompilerInvocation *CI,
517                                     llvm::IntrusiveRefCntPtr<Diagnostic> Diags,
518                                             bool OnlyLocalDecls = false,
519                                             bool CaptureDiagnostics = false,
520                                             bool PrecompilePreamble = false,
521                                          bool CompleteTranslationUnit = true,
522                                       bool CacheCodeCompletionResults = false);
523
524  /// LoadFromCommandLine - Create an ASTUnit from a vector of command line
525  /// arguments, which must specify exactly one source file.
526  ///
527  /// \param ArgBegin - The beginning of the argument vector.
528  ///
529  /// \param ArgEnd - The end of the argument vector.
530  ///
531  /// \param Diags - The diagnostics engine to use for reporting errors; its
532  /// lifetime is expected to extend past that of the returned ASTUnit.
533  ///
534  /// \param ResourceFilesPath - The path to the compiler resource files.
535  //
536  // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
537  // shouldn't need to specify them at construction time.
538  static ASTUnit *LoadFromCommandLine(const char **ArgBegin,
539                                      const char **ArgEnd,
540                                    llvm::IntrusiveRefCntPtr<Diagnostic> Diags,
541                                      llvm::StringRef ResourceFilesPath,
542                                      bool OnlyLocalDecls = false,
543                                      RemappedFile *RemappedFiles = 0,
544                                      unsigned NumRemappedFiles = 0,
545                                      bool CaptureDiagnostics = false,
546                                      bool PrecompilePreamble = false,
547                                      bool CompleteTranslationUnit = true,
548                                      bool CacheCodeCompletionResults = false,
549                                      bool CXXPrecompilePreamble = false,
550                                      bool CXXChainedPCH = false);
551
552  /// \brief Reparse the source files using the same command-line options that
553  /// were originally used to produce this translation unit.
554  ///
555  /// \returns True if a failure occurred that causes the ASTUnit not to
556  /// contain any translation-unit information, false otherwise.
557  bool Reparse(RemappedFile *RemappedFiles = 0,
558               unsigned NumRemappedFiles = 0);
559
560  /// \brief Perform code completion at the given file, line, and
561  /// column within this translation unit.
562  ///
563  /// \param File The file in which code completion will occur.
564  ///
565  /// \param Line The line at which code completion will occur.
566  ///
567  /// \param Column The column at which code completion will occur.
568  ///
569  /// \param IncludeMacros Whether to include macros in the code-completion
570  /// results.
571  ///
572  /// \param IncludeCodePatterns Whether to include code patterns (such as a
573  /// for loop) in the code-completion results.
574  ///
575  /// FIXME: The Diag, LangOpts, SourceMgr, FileMgr, StoredDiagnostics, and
576  /// OwnedBuffers parameters are all disgusting hacks. They will go away.
577  void CodeComplete(llvm::StringRef File, unsigned Line, unsigned Column,
578                    RemappedFile *RemappedFiles, unsigned NumRemappedFiles,
579                    bool IncludeMacros, bool IncludeCodePatterns,
580                    CodeCompleteConsumer &Consumer,
581                    Diagnostic &Diag, LangOptions &LangOpts,
582                    SourceManager &SourceMgr, FileManager &FileMgr,
583                    llvm::SmallVectorImpl<StoredDiagnostic> &StoredDiagnostics,
584              llvm::SmallVectorImpl<const llvm::MemoryBuffer *> &OwnedBuffers);
585
586  /// \brief Save this translation unit to a file with the given name.
587  ///
588  /// \returns True if an error occurred, false otherwise.
589  bool Save(llvm::StringRef File);
590};
591
592} // namespace clang
593
594#endif
595