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