[clangd] Add fallback mode for code completion when compile command or preamble is not ready.

[ioeric]

Summary

When calling TUScehduler::runWithPreamble (e.g. in code compleiton), allow
entering a fallback mode when compile command or preamble is not ready, instead of
waiting. This allows clangd to perform naive code completion e.g. using identifiers
in the current file or symbols in the index.

This patch simply returns empty result for code completion in fallback mode. Identifier-based
plus more advanced index-based completion will be added in followup patches.

[ilya-biryukov]

I think this option should be configurable (and off by default) for the transition period. A few reasons to do so:

• Before we have an actual implementation of fallback completions, the current behavior (waiting for the first preamble) actually seems like a better experience than returning empty results.
• Some clients do this kind of fallback on their own (e.g. VSCode), so until we can provide actually semantically interesting results (anything more than identifier-based really, e.g. keyword completions) we would be better off keeping it off.
• We can still test it if it's off by flipping the corresponding flag in the test code.
• Would make rollout easier (clients can flip the flag back and forth and make sure it does not break stuff for them)

clangd/ClangdServer.cpp

190

This way we don't distinguish between the failure to build a preamble and the fallback mode.
Have you considered introducing a different callback instead to clearly separate two cases for the clients?
The code handling those would hardly have any similarities anyway, given that the nature of those two cases is so different.

Would look something like this:

/// When \p FallbackAction is not null, it would be called instead of \p Action in cases when preamble is 
/// not yet ready.
void runWithPreamble(… Callback<InputsAndPreamble> Action, Callback<Inputs> FallbackAction);

clangd/TUScheduler.cpp

184–185

Could we put the preamble and compile command into a single function?
Getting them in the lock-step would mean they're always consistent, which is a good thing.

256

NIT: name it LastCompileCommand for consistency with the name of LastBuiltPreamble.

355

After this point the clients might start getting a new compile command and an old preamble.
This seems fine (the clients should be ready for this), but let's document it in the methods that expose a compile command and a preamble.

881

It would be better to make a decision on whether to use a fallback mode in the actual function scheduled on a different thread (i.e. inside the body of Task).
Imagine the preamble is being built right now and would finish before scheduling this task. In that case we would have a chance to hit the "preamble" if we make a decision in the body of the handler, but won't have that chance in the current implementation.

936

NIT: remove braces

clangd/TUScheduler.h

37

How would we expect to use the compile command when preamble is not ready?
Maybe go with passing only contents to the fallback action until we actually have a use for compile command?

148

NIT: keep the parameter named Inputs

unittests/clangd/ClangdTests.cpp

1100

Could we provide a flag in the results indicating this was a fallback-mode completion?
This could be used here in tests and we could later use it in the clients to show the corresponding UI indicators for users.

[ioeric]

• address review comments.

[ioeric]

In D59811#1445701, @ilya-biryukov wrote:

I think this option should be configurable (and off by default) for the transition period. A few reasons to do so:

• Before we have an actual implementation of fallback completions, the current behavior (waiting for the first preamble) actually seems like a better experience than returning empty results.
• Some clients do this kind of fallback on their own (e.g. VSCode), so until we can provide actually semantically interesting results (anything more than identifier-based really, e.g. keyword completions) we would be better off keeping it off.
• We can still test it if it's off by flipping the corresponding flag in the test code.
• Would make rollout easier (clients can flip the flag back and forth and make sure it does not break stuff for them)

All very good points. Thanks! I've added an option.

clangd/ClangdServer.cpp

190

void runWithPreamble(… Callback<InputsAndPreamble> Action, Callback<Inputs> FallbackAction);

This is what I started with in the first iteration. The main problem is that we would need to bind CB to both actions; however, CB is not copyable/shareable by design, I think. This seems to leave us with the only option to handle everything in the same action. I thought this was fine because an parameter AllowFallback seems to be clear as well. I'm open to suggestions ;)

This way we don't distinguish between the failure to build a preamble and the fallback mode.

I am assuming that a fallback for runWithPreamble is either compile command is missing/broken or preamble fails to be built. And in both cases, fallback mode could be useful. Do you think we should have more distinctions made here?

clangd/TUScheduler.cpp

184–185

Could you elaborate the advantages of keeping them consistent?

They seem to be updated and used relatively independently. Grouping them into one function seems to add more work to the call sites. And it seems inevitable that we would some inconsistency between the two.

355

After this point the clients might start getting a new compile command and an old preamble.

Did we have guarantee about this before? It seems that we could also have the similar situation.

This seems fine (the clients should be ready for this), but let's document it in the methods that expose a compile command and a preamble.

I added documentation for getCurrentPreamble; would it be the right place? getPossiblyStalePreamble seems self-explaining enough. And since compile command is always fresher than preamble, I think it would be fine without commenting?

881

It sounds like a very small window (~ms?) that we are trying to optimize for. Given that users type relatively slow and the first preamble usually only becomes ready for each file once, it seems unlikely to get value out of this often. And once the preamble is built, the decision is likely to be always no fallback, so it would be a bit wasteful to run a separate task for this.

clangd/TUScheduler.h

37

We could potentially use compile command to shorten includes for headers from global index.

The intention here was to share the same action and thus the same input structure for both modes.

unittests/clangd/ClangdTests.cpp

1100

Good point. I just realized we could use the Context that already exists in the result. We will set it to Recovery in fallback mode. Although sema can also enter recovery mode, they don't seem to conflict much? WDYT?

[ioeric]

• Rebase

[ilya-biryukov]

Leaving a few first comments, have to run.
Will take another look later, sorry about the delay today (also feel free to add more reviewers in case this is urgent).

clangd/ClangdServer.cpp

190

Ah, right, I did not realize that design of Callback makes it hard for two callbacks to own the same data.
And that's what we technically need for this. I'll have to think about this two, maybe there's a better way to express this in the code (AllowFallback looks like the option with least amount of friction so far).

clangd/TUScheduler.cpp

184–185

I was originally thinking about consistency between the provided compile command and the one used to build the preamble.
Now I realize that they are set at different times, so we can't really make them consistent (unless we decide to delay the update of the compile command, but I don't see why it's useful).

You approach looks legit, but could you please document in these getters (maybe more importantly in the public callback interfaces?) that preamble and compile commands might be out of sync (command can be newer) and clients should handle that gracefully.

[sammccall]

Got here trying to understand how D60126 works.

It seems there's two fairly independent changes here:

• the one described, allow actions to run without a preamble
• defer the blocking getCompileCommand() call until we're building the preamble

Certainly they interact to make zero-latency code completion work, but is it possible to pull the latter out of this patch?
There are other approaches to the second part (e.g. giving TUScheduler a reference to the global CDB) that might be cleaner. I don't think it needs to block D60126.

clangd/TUScheduler.h

200

I think this isn't orthogonal to PreambleConsistency.
When would we use AllowFallback = true but PreambleConsistency = Consistent?

Two possible options:

• adding a new StaleOrAbsent option to PreambleConsistency
• changing Stale to these new semantics, as codeComplete is the only caller

The problem with the latter is we can't put it behind a flag.

[ilya-biryukov]

Sam, thanks for taking a look and the useful comments!

@ioeric, I second Sam's suggestion to split the compile command and the fallback action into two changes. This would make it easier to review those in isolation. Could you do this please?

clangd/TUScheduler.h

200

Ah, I was totally looking past the PreambleConsistency flag.
Thanks for spotting this. Indeed, modeling the fallback in the PreambleConsistency would make sense.

[ioeric]

• split out the compile command change.

[ioeric]

clangd/TUScheduler.h

200

Sounds good. Thanks for the suggestion!

[ioeric]

Oops, forgot to update tests...

[ioeric]

• Fix unit test

[sammccall]

API looks good. Implementation looks like it can be simplified a bit, unless I'm missing something.

clangd/CodeComplete.h

117

nit: "mode" doesn't add anything here

clangd/TUScheduler.cpp

50

not needed or bad patch base?

51

not needed?

881

Does this need to be a special case at the top of TUScheduler::runWithPreamble, rather than unified with the rest of the body?

e.g. the if (!PreambleTasks) appears to block appears to handle that case correctly already, and the Consistency == Consistent block won't trigger.
I think all you need to do is make the Worker->waitForFirstPreamble() line conditional?

(This means no changes to ASTWorker, Notification etc)

clangd/TUScheduler.h

190–196

This sentence has grown unwieldy:can we just say "If there's no up-to-date preamble, we follow the PreambleConsistency policy"?
(I personally find the \p s hurt readability, but up to you)

193

bad reflow, break before "if an error occurs" (or just drop the sentence)

194

I think this is a bad reflow, need a line break before "Context cancellation is ignored..."

unittests/clangd/ClangdTests.cpp

1068

does this comment need an update?

1082

do I understand right that this test is currently racy?

[sammccall]

unittests/clangd/ClangdTests.cpp

1080

(-this-flag-does-not-exist might be clearer)

1082

Sorry, missed your comment. Test LG

[ioeric]

• address review comments

clangd/TUScheduler.cpp

881

whoops! absolutely right!

unittests/clangd/ClangdTests.cpp

1080

This would still cause preamble to be built:

Updating file /clangd-test/foo.cpp with command [/clangd-test] clang -this-flag-does-not-exist /clangd-test/foo.cpp
Ignored diagnostic. unknown argument: '-this-flag-does-not-exist'

[sammccall]

Thanks!

clangd/ClangdServer.cpp

 //===--- ClangdServer.cpp - Main clangd server code --------------*- C++-*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===-------------------------------------------------------------------===//
 
 #include "ClangdServer.h"
 #include "ClangdUnit.h"
 #include "CodeComplete.h"
 #include "FindSymbols.h"
 #include "Headers.h"
+#include "Protocol.h"
 #include "SourceCode.h"
+#include "TUScheduler.h"
 #include "Trace.h"
 #include "index/CanonicalIncludes.h"
 #include "index/FileIndex.h"
 #include "index/Merge.h"
 #include "refactor/Tweak.h"
 #include "clang/Format/Format.h"
 #include "clang/Frontend/CompilerInstance.h"
 #include "clang/Frontend/CompilerInvocation.h"
 #include "clang/Lex/Preprocessor.h"
+#include "clang/Sema/CodeCompleteConsumer.h"
 #include "clang/Tooling/CompilationDatabase.h"
 #include "clang/Tooling/Core/Replacement.h"
 #include "clang/Tooling/Refactoring/RefactoringResultConsumer.h"
 #include "clang/Tooling/Refactoring/Rename/RenamingAction.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/Optional.h"
 #include "llvm/ADT/ScopeExit.h"
 #include "llvm/ADT/StringRef.h"

 
 void ClangdServer::addDocument(PathRef File, llvm::StringRef Contents,
                                WantDiagnostics WantDiags) {
   ParseOptions Opts;
   Opts.ClangTidyOpts = tidy::ClangTidyOptions::getDefaults();
   if (ClangTidyOptProvider)
     Opts.ClangTidyOpts = ClangTidyOptProvider->getOptions(File);
   Opts.SuggestMissingIncludes = SuggestMissingIncludes;
+
   // FIXME: some build systems like Bazel will take time to preparing
   // environment to build the file, it would be nice if we could emit a
   // "PreparingBuild" status to inform users, it is non-trivial given the
   // current implementation.
   ParseInputs Inputs;
   Inputs.CompileCommand = getCompileCommand(File);
   Inputs.FS = FSProvider.getFileSystem();
   Inputs.Contents = Contents;
void ClangdServer::codeComplete(PathRef File, Position Pos,
   auto FS = FSProvider.getFileSystem();
   auto Task = [Pos, FS, CodeCompleteOpts,
                this](Path File, Callback<CodeCompleteResult> CB,
                      llvm::Expected<InputsAndPreamble> IP) {
     if (!IP)
       return CB(IP.takeError());
     if (isCancelled())
       return CB(llvm::make_error<CancelledError>());
+    if (!IP->Preamble) {
+      vlog("File {0} is not ready for code completion. Enter fallback mode.",
+           File);
+      CodeCompleteResult CCR;
+      CCR.Context = CodeCompletionContext::CCC_Recovery;
+
+      // FIXME: perform simple completion e.g. using identifiers in the current
+      // file and symbols in the index.
+      // FIXME: let clients know that we've entered fallback mode.
+
+      return CB(std::move(CCR));
+    }
 
     llvm::Optional<SpeculativeFuzzyFind> SpecFuzzyFind;
     if (CodeCompleteOpts.Index && CodeCompleteOpts.SpeculativeIndexRequest) {
       SpecFuzzyFind.emplace();
       {
         std::lock_guard<std::mutex> Lock(CachedCompletionFuzzyFindRequestMutex);
         SpecFuzzyFind->CachedReq = CachedCompletionFuzzyFindRequestByFile[File];
       }
auto Task = [Pos, FS, CodeCompleteOpts,
     }
     // SpecFuzzyFind is only destroyed after speculative fuzzy find finishes.
     // We don't want `codeComplete` to wait for the async call if it doesn't use
     // the result (e.g. non-index completion, speculation fails), so that `CB`
     // is called as soon as results are available.
   };
 
   // We use a potentially-stale preamble because latency is critical here.
-  WorkScheduler.runWithPreamble("CodeComplete", File, TUScheduler::Stale,
-                                Bind(Task, File.str(), std::move(CB)));
+  WorkScheduler.runWithPreamble(
+      "CodeComplete", File,
+      Opts.AllowFallbackMode ? TUScheduler::StaleOrAbsent : TUScheduler::Stale,
 }
 
 void ClangdServer::signatureHelp(PathRef File, Position Pos,
                                  Callback<SignatureHelp> CB) {
 
   auto FS = FSProvider.getFileSystem();
   auto *Index = this->Index;
   auto Action = [Pos, FS, Index](Path File, Callback<SignatureHelp> CB,

clangd/CodeComplete.h

struct CodeCompleteOptions {
   bool EnableFunctionArgSnippets = true;
 
   /// Whether to include index symbols that are not defined in the scopes
   /// visible from the code completion point. This applies in contexts without
   /// explicit scope qualifiers.
   ///
   /// Such completions can insert scope qualifiers.
   bool AllScopes = false;
+
+  /// Whether to allow falling back to code completion without compiling files
+  /// (using identifiers in the current file and symbol indexes), when file
+  /// cannot be built (e.g. missing compile command), or the build is not ready
+  /// (e.g. preamble is still being built).
+  bool AllowFallbackMode = false;
 };
 
 // Semi-structured representation of a code-complete suggestion for our C++ API.
 // We don't use the LSP structures here (unlike most features) as we want
 // to expose more data to allow for more precise testing and evaluation.
 struct CodeCompletion {
   // The unqualified name of the symbol or other completion item.
   std::string Name;

clangd/TUScheduler.h

 //===--- TUScheduler.h -------------------------------------------*-C++-*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_TUSCHEDULER_H
 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_TUSCHEDULER_H
 
 #include "ClangdUnit.h"
 #include "Function.h"
 #include "Threading.h"
 #include "index/CanonicalIncludes.h"
+#include "llvm/ADT/Optional.h"
 #include "llvm/ADT/StringMap.h"
+#include "llvm/ADT/StringRef.h"
 #include <future>
 
 namespace clang {
 namespace clangd {
 
 /// Returns a number of a default async threads to use for TUScheduler.
 /// Returned value is always >= 1 (i.e. will not cause requests to be processed
 /// synchronously).
 unsigned getDefaultAsyncThreadsCount();
 
 struct InputsAndAST {
   const ParseInputs &Inputs;
   ParsedAST &AST;
 };
 
 struct InputsAndPreamble {
   llvm::StringRef Contents;
   const tooling::CompileCommand &Command;
+  // This can be nullptr if no preamble is availble.
   const PreambleData *Preamble;
 };
 
 /// Determines whether diagnostics should be generated for a file snapshot.
 enum class WantDiagnostics {
   Yes,  /// Diagnostics must be generated for this snapshot.
   No,   /// Diagnostics must not be generated for this snapshot.
   Auto, /// Diagnostics must be generated for this snapshot or a subsequent one,
public:
   /// contain files that currently run something over their AST.
   std::vector<Path> getFilesWithCachedAST() const;
 
   /// Schedule an update for \p File. Adds \p File to a list of tracked files if
   /// \p File was not part of it before.
   /// If diagnostics are requested (Yes), and the context is cancelled before
   /// they are prepared, they may be skipped if eventual-consistency permits it
   /// (i.e. WantDiagnostics is downgraded to Auto).
   void update(PathRef File, ParseInputs Inputs, WantDiagnostics WD);
 
   /// Remove \p File from the list of tracked files and schedule removal of its
   /// resources. Pending diagnostics for closed files may not be delivered, even
   /// if requested with WantDiags::Auto or WantDiags::Yes.
   void remove(PathRef File);
 
   /// Schedule an async task with no dependencies.
   void run(llvm::StringRef Name, llvm::unique_function<void()> Action);
enum PreambleConsistency {
     /// The preamble may be generated from an older version of the file.
     /// Reading from locations in the preamble may cause files to be re-read.
     /// This gives callers two options:
     /// - validate that the preamble is still valid, and only use it if so
     /// - accept that the preamble contents may be outdated, and try to avoid
     ///   reading source code from headers.
     /// This is the fastest option, usually a preamble is available immediately.
     Stale,
+    /// Besides accepting stale preamble, this also allow preamble to be absent
+    /// (not ready or failed to build).
+    StaleOrAbsent,
   };
+
   /// Schedule an async read of the preamble.
-  /// If there's no preamble yet (because the file was just opened), we'll wait
-  /// for it to build. The result may be null if it fails to build or is empty.
-  /// If an error occurs, it is forwarded to the \p Action callback.
-  /// Context cancellation is ignored and should be handled by the Action.
-  /// (In practice, the Action is almost always executed immediately).
+  /// If there's no preamble yet (because the file was just opened), we'll
+  /// either run \p Action without preamble (if \p Consistency is
+  /// `StaleOrAbsent`) or wait for it to build. The result may be null, if it
+  /// fails to build, or empty if there's no include. If an error occurs, it is
+  /// forwarded to the \p Action callback. Context cancellation is ignored and
+  /// should be handled by the Action. (In practice, the Action is almost always
+  /// executed immediately).
   void runWithPreamble(llvm::StringRef Name, PathRef File,
                        PreambleConsistency Consistency,
                        Callback<InputsAndPreamble> Action);
 
   /// Wait until there are no scheduled or running tasks.
   /// Mostly useful for synchronizing tests.
   bool blockUntilIdle(Deadline D) const;
 
 private:
   /// This class stores per-file data in the Files map.
   struct FileData;
 

clangd/TUScheduler.cpp

 //   immediately.
 
 #include "TUScheduler.h"
 #include "Cancellation.h"
 #include "Logger.h"
 #include "Trace.h"
 #include "index/CanonicalIncludes.h"
 #include "clang/Frontend/CompilerInvocation.h"
+#include "clang/Frontend/PCHContainerOperations.h"
+#include "clang/Tooling/CompilationDatabase.h"
+#include "llvm/ADT/Optional.h"
 #include "llvm/ADT/ScopeExit.h"
 #include "llvm/Support/Errc.h"
 #include "llvm/Support/Path.h"
 #include <algorithm>
 #include <memory>
 #include <queue>
 #include <thread>
 
public:
   ~ASTWorker();
 
   void update(ParseInputs Inputs, WantDiagnostics);
   void
   runWithAST(llvm::StringRef Name,
              llvm::unique_function<void(llvm::Expected<InputsAndAST>)> Action);
   bool blockUntilIdle(Deadline Timeout) const;
 
   std::shared_ptr<const PreambleData> getPossiblyStalePreamble() const;
+
   /// Obtain a preamble reflecting all updates so far. Threadsafe.
   /// It may be delivered immediately, or later on the worker thread.
   void getCurrentPreamble(
       llvm::unique_function<void(std::shared_ptr<const PreambleData>)>);
   /// Wait for the first build of preamble to finish. Preamble itself can be
   /// accessed via getPossiblyStalePreamble(). Note that this function will
   /// return after an unsuccessful build of the preamble too, i.e. result of
   /// getPossiblyStalePreamble() can be null even after this function returns.
   void waitForFirstPreamble() const;
+  bool isFirstPreambleBuilt() const;
 
   std::size_t getUsedBytes() const;
   bool isASTCached() const;
 
 private:
   // Must be called exactly once on processing thread. Will return after
   // stop() is called on a separate thread and all pending requests are
   // processed.
private:
   TUStatus Status;
 
   Semaphore &Barrier;
   /// Inputs, corresponding to the current state of AST.
   ParseInputs FileInputs;
   /// Whether the diagnostics for the current FileInputs were reported to the
   /// users before.
   bool DiagsWereReported = false;
-  /// Size of the last AST
   /// Guards members used by both TUScheduler and the worker thread.
   mutable std::mutex Mutex;
   std::shared_ptr<const PreambleData> LastBuiltPreamble; /* GUARDED_BY(Mutex) */
   /// Becomes ready when the first preamble build finishes.
   Notification PreambleWasBuilt;
   /// Set to true to signal run() to finish processing.
   bool Done;                    /* GUARDED_BY(Mutex) */
   std::deque<Request> Requests; /* GUARDED_BY(Mutex) */
   mutable std::condition_variable RequestsCV;
   // FIXME: rename it to better fix the current usage, we also use it to guard
   // emitting TUStatus.
   /// Guards a critical section for running the diagnostics callbacks.
   std::mutex DiagsMu;
   // Used to prevent remove document + leading to out-of-order diagnostics:
   // The lifetime of the old/new ASTWorkers will overlap, but their handles

 
 void ASTWorker::update(ParseInputs Inputs, WantDiagnostics WantDiags) {
   llvm::StringRef TaskName = "Update";
   auto Task = [=]() mutable {
     // Will be used to check if we can avoid rebuilding the AST.
     bool InputsAreTheSame =
         std::tie(FileInputs.CompileCommand, FileInputs.Contents) ==
         std::tie(Inputs.CompileCommand, Inputs.Contents);
 
     tooling::CompileCommand OldCommand = std::move(FileInputs.CompileCommand);
     bool PrevDiagsWereReported = DiagsWereReported;
     FileInputs = Inputs;
     DiagsWereReported = false;
     emitTUStatus({TUAction::BuildingPreamble, TaskName});
     log("Updating file {0} with command [{1}] {2}", FileName,
         Inputs.CompileCommand.Directory,
         llvm::join(Inputs.CompileCommand.CommandLine, " "));
Requests.insert(LastUpdate.base(),
                           Context::current().clone(),
                           /*UpdateType=*/None});
   Lock.unlock();
   RequestsCV.notify_all();
 }
 
 void ASTWorker::waitForFirstPreamble() const { PreambleWasBuilt.wait(); }
 
+bool ASTWorker::isFirstPreambleBuilt() const {
+  return PreambleWasBuilt.notified();
+}
+
 std::size_t ASTWorker::getUsedBytes() const {
   // Note that we don't report the size of ASTs currently used for processing
   // the in-flight requests. We used this information for debugging purposes
   // only, so this should be fine.
   std::size_t Result = IdleASTs.getUsedBytes(this);
   if (auto Preamble = getPossiblyStalePreamble())
     Result += Preamble->Preamble.getSize();
   return Result;
if (It == Files.end()) {
     Action(llvm::make_error<LSPError>(
         "trying to get AST for non-added document", ErrorCode::InvalidParams));
     return;
   }
 
   It->second->Worker->runWithAST(Name, std::move(Action));
 }
 
-void TUScheduler::runWithPreamble(
-    llvm::StringRef Name, PathRef File, PreambleConsistency Consistency,
-    llvm::unique_function<void(llvm::Expected<InputsAndPreamble>)> Action) {
+void TUScheduler::runWithPreamble(llvm::StringRef Name, PathRef File,
+                                  PreambleConsistency Consistency,
+                                  Callback<InputsAndPreamble> Action) {
   auto It = Files.find(File);
   if (It == Files.end()) {
     Action(llvm::make_error<LSPError>(
         "trying to get preamble for non-added document",
         ErrorCode::InvalidParams));
     return;
   }
+  // Enter fallback mode if preamble is not ready. We only do this in
+  // asynchronous mode, as TU update should finish before this is run.
+  if (!It->second->Worker->isFirstPreambleBuilt() &&
+      Consistency == StaleOrAbsent && PreambleTasks) {
+    std::shared_ptr<const ASTWorker> Worker = It->second->Worker.lock();
+    auto FallbackTask = [Worker, this](std::string Name, std::string File,
+                                       std::string Contents,
+                                       tooling::CompileCommand Command,
+                                       Context Ctx,
+                                       decltype(Action) Action) mutable {
+      std::lock_guard<Semaphore> BarrierLock(Barrier);
+      WithContext Guard(std::move(Ctx));
+      trace::Span Tracer(Name + "(fallback)");
+      SPAN_ATTACH(Tracer, "file", File);
+      Action(InputsAndPreamble{Contents, Command,
+                               /*Preamble=*/nullptr});
+    };
+
+    PreambleTasks->runAsync(
+        "task(fallback):" + llvm::sys::path::filename(File),
+        Bind(FallbackTask, std::string(Name), std::string(File),
+             It->second->Contents, It->second->Command,
+             Context::current().derive(kFileBeingProcessed, File),
+             std::move(Action)));
+    return;
+  }
 
   if (!PreambleTasks) {
     trace::Span Tracer(Name);
     SPAN_ATTACH(Tracer, "file", File);
     std::shared_ptr<const PreambleData> Preamble =
         It->second->Worker->getPossiblyStalePreamble();
     Action(InputsAndPreamble{It->second->Contents, It->second->Command,
                              Preamble.get()});
void TUScheduler::runWithPreamble(llvm::StringRef Name, PathRef File,
 
   std::shared_ptr<const ASTWorker> Worker = It->second->Worker.lock();
   auto Task = [Worker, this](std::string Name, std::string File,
                              std::string Contents,
                              tooling::CompileCommand Command, Context Ctx,
                              decltype(ConsistentPreamble) ConsistentPreamble,
                              decltype(Action) Action) mutable {
     std::shared_ptr<const PreambleData> Preamble;
     if (ConsistentPreamble.valid()) {
       Preamble = ConsistentPreamble.get();
     } else {
       // We don't want to be running preamble actions before the preamble was
       // built for the first time. This avoids extra work of processing the
       // preamble headers in parallel multiple times.
       Worker->waitForFirstPreamble();
       Preamble = Worker->getPossiblyStalePreamble();
     }

clangd/Threading.h

 namespace clang {
 namespace clangd {
 
 /// A threadsafe flag that is initially clear.
 class Notification {
 public:
   // Sets the flag. No-op if already set.
   void notify();
+  bool notified() const { return Notified; }
   // Blocks until flag is set.
   void wait() const;
 
 private:
   bool Notified = false;
   mutable std::condition_variable CV;
   mutable std::mutex Mu;
 };

clangd/tool/ClangdMain.cpp

static llvm::cl::opt<OffsetEncoding> ForceOffsetEncoding(
     llvm::cl::desc("Force the offsetEncoding used for character positions. "
                    "This bypasses negotiation via client capabilities."),
     llvm::cl::values(clEnumValN(OffsetEncoding::UTF8, "utf-8",
                                 "Offsets are in UTF-8 bytes"),
                      clEnumValN(OffsetEncoding::UTF16, "utf-16",
                                 "Offsets are in UTF-16 code units")),
     llvm::cl::init(OffsetEncoding::UnsupportedEncoding));
 
+static llvm::cl::opt<bool> AllowFallbackCompletion(
+    "allow-fallback-completion",
+    llvm::cl::desc(
+        "Allow falling back to code completion without compiling files (using "
+        "identifiers and symbol indexes), when file cannot be built or the "
+        "build is not ready."),
+    llvm::cl::init(false));
+
 namespace {
 
 /// \brief Supports a test URI scheme with relaxed constraints for lit tests.
 /// The path in a test URI will be combined with a platform-specific fake
 /// directory to form an absolute path. For example, test:///a.cpp is resolved
 /// C:\clangd-test\a.cpp on Windows and /clangd-test/a.cpp on Unix.
 class TestScheme : public URIScheme {
 public:
int main(int argc, char *argv[]) {
   CCOpts.ShowOrigins = ShowOrigins;
   if (!HeaderInsertionDecorators) {
     CCOpts.IncludeIndicator.Insert.clear();
     CCOpts.IncludeIndicator.NoInsert.clear();
   }
   CCOpts.SpeculativeIndexRequest = Opts.StaticIndex;
   CCOpts.EnableFunctionArgSnippets = EnableFunctionArgSnippets;
   CCOpts.AllScopes = AllScopesCompletion;
+  CCOpts.AllowFallbackMode = AllowFallbackCompletion;
 
   RealFileSystemProvider FSProvider;
   // Initialize and run ClangdLSPServer.
   // Change stdin to binary to not lose \r\n on windows.
   llvm::sys::ChangeStdinToBinary();
 
   std::unique_ptr<Transport> TransportLayer;
   if (getenv("CLANGD_AS_XPC_SERVICE")) {

unittests/clangd/ClangdTests.cpp

 //===-- ClangdTests.cpp - Clangd unit tests ---------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "Annotations.h"
 #include "ClangdLSPServer.h"
 #include "ClangdServer.h"
 #include "GlobalCompilationDatabase.h"
 #include "Matchers.h"
 #include "SyncAPI.h"
 #include "TestFS.h"
+#include "Threading.h"
 #include "URI.h"
 #include "clang/Config/config.h"
+#include "clang/Sema/CodeCompleteConsumer.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/ADT/StringMap.h"
 #include "llvm/Support/Errc.h"
 #include "llvm/Support/Path.h"
 #include "llvm/Support/Regex.h"
 #include "gmock/gmock.h"
 #include "gtest/gtest.h"
 #include <algorithm>
 #include <chrono>
 #include <iostream>
 #include <random>
 #include <string>
 #include <thread>
 #include <vector>
 
 namespace clang {
 namespace clangd {
 
 namespace {
 
 using ::testing::ElementsAre;
-using ::testing::Eq;
 using ::testing::Field;
 using ::testing::Gt;
 using ::testing::IsEmpty;
 using ::testing::Pair;
 using ::testing::UnorderedElementsAre;
 
 MATCHER_P2(DeclAt, File, Range, "") {
   return arg.PreferredDeclaration ==
TEST_F(ClangdVFSTest, FlagsWithPlugins) {
   const auto SourceContents = "int main() { return 0; }";
   FS.Files[FooCpp] = FooCpp;
   Server.addDocument(FooCpp, SourceContents);
   auto Result = dumpASTWithoutMemoryLocs(Server, FooCpp);
   EXPECT_TRUE(Server.blockUntilIdleForTest()) << "Waiting for diagnostics";
   EXPECT_NE(Result, "<no-ast>");
 }
 
+TEST_F(ClangdVFSTest, FallbackWhenPreambleIsNotReady) {
+  MockFSProvider FS;
+  ErrorCheckingDiagConsumer DiagConsumer;
+  MockCompilationDatabase CDB;
+  ClangdServer Server(CDB, FS, DiagConsumer, ClangdServer::optsForTest());
+
+  auto FooCpp = testPath("foo.cpp");
+  Annotations Code(R"cpp(
+    int main() {
+      int xyz;
+      xy^
+    })cpp");
+  FS.Files[FooCpp] = FooCpp;
+
+  auto Opts = clangd::CodeCompleteOptions();
+  Opts.AllowFallbackMode = true;
+
+  // This will make compile command broken and preamble absent.
+  CDB.ExtraClangFlags = {"yolo.cc"};
+  Server.addDocument(FooCpp, Code.code());
+  ASSERT_TRUE(Server.blockUntilIdleForTest());
+  auto Res = cantFail(runCodeComplete(Server, FooCpp, Code.point(), Opts));
+  EXPECT_THAT(Res.Completions, IsEmpty());
+  EXPECT_EQ(Res.Context, CodeCompletionContext::CCC_Recovery);
+
+  // Make the compile command work again.
+  CDB.ExtraClangFlags = {"-std=c++11"};
+  Server.addDocument(FooCpp, Code.code());
+  ASSERT_TRUE(Server.blockUntilIdleForTest());
+  EXPECT_THAT(cantFail(runCodeComplete(Server, FooCpp, Code.point(),
+                                       Opts))
+                  .Completions,
+              ElementsAre(Field(&CodeCompletion::Name, "xyz")));
+}
+
 } // namespace
 } // namespace clangd
 } // namespace clang