[libclang] Allow to suspend a translation unit.

[nik]

Summary

A suspended translation unit uses significantly less memory but on the other
side does not support any other calls than clang_reparseTranslationUnit to
resume it or clang_disposeTranslationUnit to dispose it completely.

This helps IDEs to reduce the memory footprint. The data that is freed
by a call to clang_suspendTranslationUnit will be re-generated on the
next (re)parse anyway. Used with a preamble, this allows pretty fast
resumption of the translation unit for further use (compared to disposal of
the translation unit and a parse from scratch).

[nik]

Ping :)

[bkramer]

This makes sense to me.

lib/Frontend/ASTUnit.cpp

2089

Put the { on the same line as the decl.

[nik]

Adapted to the changes that happened in the meanwhile (CINDEX_VERSION_MINOR increased, CleanTemporaryFiles got removed).

[nik]

I'm new to this review tool. I've addressed the comments and rebased. Does this needs a re-review? Note that this is my first change and I probably do not have any permissions to submit this change.

[erikjv]

Committed as r304212.

include/clang-c/Index.h

  * \brief The version constants for the libclang API.
  * CINDEX_VERSION_MINOR should increase when there are API additions.
  * CINDEX_VERSION_MAJOR is intended for "major" source/ABI breaking changes.
  *
  * The policy about the libclang API was always to keep it source and ABI
  * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable.
  */
 #define CINDEX_VERSION_MAJOR 0
-#define CINDEX_VERSION_MINOR 38
+#define CINDEX_VERSION_MINOR 39
 
 #define CINDEX_VERSION_ENCODE(major, minor) ( \
       ((major) * 10000)                       \
     + ((minor) *     1))
 
 #define CINDEX_VERSION CINDEX_VERSION_ENCODE( \
     CINDEX_VERSION_MAJOR,                     \
     CINDEX_VERSION_MINOR )

  * enumeration. Zero (CXSaveError_None) indicates that the translation unit was 
  * saved successfully, while a non-zero value indicates that a problem occurred.
  */
 CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU,
                                              const char *FileName,
                                              unsigned options);
 
 /**
+ * \brief Suspend a translation unit in order to free memory associated with it.
+ *
+ * A suspended translation unit uses significantly less memory but on the other
+ * side does not support any other calls than \c clang_reparseTranslationUnit
+ * to resume it or \c clang_disposeTranslationUnit to dispose it completely.
+ */
+CINDEX_LINKAGE unsigned clang_suspendTranslationUnit(CXTranslationUnit);
+
+/**
  * \brief Destroy the specified CXTranslationUnit object.
  */
 CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
 
 /**
  * \brief Flags that control the reparsing of translation units.
  *
  * The enumerators in this enumeration type are meant to be bitwise

include/clang/Frontend/ASTUnit.h

public:
   /// \brief Reparse the source files using the same command-line options that
   /// were originally used to produce this translation unit.
   ///
   /// \returns True if a failure occurred that causes the ASTUnit not to
   /// contain any translation-unit information, false otherwise.
   bool Reparse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
                ArrayRef<RemappedFile> RemappedFiles = None);
 
+  /// \brief Free data that will be re-generated on the next parse.
+  ///
+  /// Preamble-related data is not affected.
+  void ResetForParse();
+
   /// \brief Perform code completion at the given file, line, and
   /// column within this translation unit.
   ///
   /// \param File The file in which code completion will occur.
   ///
   /// \param Line The line at which code completion will occur.
   ///
   /// \param Column The column at which code completion will occur.

lib/Frontend/ASTUnit.cpp

 
 /// Parse the source file into a translation unit using the given compiler
 /// invocation, replacing the current translation unit.
 ///
 /// \returns True if a failure occurred that causes the ASTUnit not to
 /// contain any translation-unit information, false otherwise.
 bool ASTUnit::Parse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
                     std::unique_ptr<llvm::MemoryBuffer> OverrideMainBuffer) {
-  SavedMainFileBuffer.reset();
-
   if (!Invocation)
     return true;
 
   // Create the compiler instance to use for building the AST.
   std::unique_ptr<CompilerInstance> Clang(
       new CompilerInstance(std::move(PCHContainerOps)));
 
   // Recover resources if we crash before exiting this method.
bool ASTUnit::Parse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
 
   // Configure the various subsystems.
   LangOpts = Clang->getInvocation().LangOpts;
   FileSystemOpts = Clang->getFileSystemOpts();
   if (!FileMgr) {
     Clang->createFileManager();
     FileMgr = &Clang->getFileManager();
   }
-  SourceMgr = new SourceManager(getDiagnostics(), *FileMgr,
-                                UserFilesAreVolatile);
-  TheSema.reset();
-  Ctx = nullptr;
-  PP = nullptr;
-  Reader = nullptr;
 
-  // Clear out old caches and data.
-  TopLevelDecls.clear();
-  clearFileLevelDecls();
-  CleanTemporaryFiles();
+  ResetForParse();
 
+  SourceMgr = new SourceManager(getDiagnostics(), *FileMgr,
+                                UserFilesAreVolatile);
   if (!OverrideMainBuffer) {
     checkAndRemoveNonDriverDiags(StoredDiagnostics);
     TopLevelDeclsInPreamble.clear();
   }
 
   // Create a file manager object to provide access to and cache the filesystem.
   Clang->setFileManager(&getFileManager());
   
bool ASTUnit::Reparse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
 
   // We now need to clear out the completion info related to this translation
   // unit; it'll be recreated if necessary.
   CCTUInfo.reset();
   
   return Result;
 }
 
+void ASTUnit::ResetForParse()
+{
+  SavedMainFileBuffer.reset();
+
+  SourceMgr.reset();
+  TheSema.reset();
+  Ctx.reset();
+  PP.reset();
+  Reader.reset();
+
+  TopLevelDecls.clear();
+  clearFileLevelDecls();
+  CleanTemporaryFiles();
+}
+
 //----------------------------------------------------------------------------//
 // Code completion
 //----------------------------------------------------------------------------//
 
 namespace {
   /// \brief Code completion consumer that combines the cached code-completion
   /// results from an ASTUnit with the code-completion results provided to it,
   /// then passes the result on to 

tools/c-index-test/c-index-test.c

if (Err != CXError_Success) {
     return 1;
   }
 
   for (I = 0; I != Repeats; ++I) {
     if (checkForErrors(TU) != 0)
       return -1;
 
     if (Repeats > 1) {
+      clang_suspendTranslationUnit(TU);
+
       Err = clang_reparseTranslationUnit(TU, num_unsaved_files, unsaved_files,
                                          clang_defaultReparseOptions(TU));
       if (Err != CXError_Success) {
         describeLibclangFailure(Err);
         free_remapped_files(unsaved_files, num_unsaved_files);
         clang_disposeIndex(Idx);
         return 1;
       }

tools/libclang/CIndex.cpp

if (CTUnit) {
     delete CTUnit->StringPool;
     delete static_cast<CXDiagnosticSetImpl *>(CTUnit->Diagnostics);
     disposeOverridenCXCursorsPool(CTUnit->OverridenCursorsPool);
     delete CTUnit->CommentToXML;
     delete CTUnit;
   }
 }
 
+unsigned clang_suspendTranslationUnit(CXTranslationUnit CTUnit) {
+  if (CTUnit) {
+    ASTUnit *Unit = cxtu::getASTUnit(CTUnit);
+
+    if (Unit && Unit->isUnsafeToFree())
+      return false;
+
+    Unit->ResetForParse();
+    return true;
+  }
+
+  return false;
+}
+
 unsigned clang_defaultReparseOptions(CXTranslationUnit TU) {
   return CXReparse_None;
 }
 
 static CXErrorCode
 clang_reparseTranslationUnit_Impl(CXTranslationUnit TU,
                                   ArrayRef<CXUnsavedFile> unsaved_files,
                                   unsigned options) {

tools/libclang/libclang.exports

 clang_parseTranslationUnit
 clang_parseTranslationUnit2
 clang_parseTranslationUnit2FullArgv
 clang_remap_dispose
 clang_remap_getFilenames
 clang_remap_getNumFiles
 clang_reparseTranslationUnit
 clang_saveTranslationUnit
+clang_suspendTranslationUnit
 clang_sortCodeCompletionResults
 clang_toggleCrashRecovery
 clang_tokenize
 clang_CompilationDatabase_fromDirectory
 clang_CompilationDatabase_dispose
 clang_CompilationDatabase_getCompileCommands
 clang_CompilationDatabase_getAllCompileCommands
 clang_CompileCommands_dispose