Add Compilation "Wave" Assertion in +Asserts Builds

The "wave" of a compilation job describes the number of indirections through other compile jobs the driver required to reach the decision to schedule a job. In incremental mode, it should always be the case that it takes no more than two complete waves to arrive at a fixpoint in the build. This is a natural consequence of the structure of the dependencies emitted by the Swift frontend - namely we rely on transitivity in dependency arcs.

A quick proof sketch: Suppose an arbitrary perturbation of the inputs to an incremental compilation session are made. In the first wave, dependency edges from the prior build's state (the "zeroeth wave") are loaded and the files corresponding to invalidated edges are scheduled into the first wave. Supposing the second wave is not the null set - the trivial case - there are additional arcs that were invalidated. Now suppose that there were a third wave. Take an arbitrary arc invalidated by this third wave. It must be the case that the file containing the use is not new - else it would be scheduled. Further it must be the case that its def was not invalidated by the zeroeth or first waves of compilation otherwise we would have scheduled it into the first or second waves. Finally, it must have a use that was discovered in the second wave. But in order for that use to have been included in the second wave, there must have been an invalidated arc created by the first wave. By transitivity of dependency arcs, there must therefore be a dependency arc from a definition invalidated in the first wave to our third wave job, which implies that the file would be scheduled into the second wave!

[Insert contradiction pig image here]

Author: CodaFi

include/swift/Driver/Job.h

@@ -308,6 +308,23 @@ class Job {
   /// The modification time of the main input file, if any.
   llvm::sys::TimePoint<> InputModTime = llvm::sys::TimePoint<>::max();
 
+#ifndef NDEBUG
+  /// The "wave" of incremental jobs that this \c Job was scheduled into.
+  ///
+  /// The first "wave" of jobs is computed by the driver from the set of inputs
+  /// and external files that have been mutated by the user. From there, as
+  /// jobs from the first wave finish executing, we reload their \c swiftdeps
+  /// files and re-integrate them into the dependency graph to discover
+  /// the jobs for the second "wave".
+  ///
+  /// In +asserts builds, we ensure that no more than two "waves" occur for
+  /// any given incremental compilation session. This is a consequence of
+  /// 1) transitivity in dependency arcs
+  /// 2) dependency tracing from uses that affect a def's interfaces to that
+  ///    def's uses.
+  mutable unsigned Wave = 1;
+#endif
+
 public:
   Job(const JobAction &Source, SmallVectorImpl<const Job *> &&Inputs,
       std::unique_ptr<CommandOutput> Output, const char *Executable,
@@ -399,6 +416,11 @@ class Job {
   /// Assumes that, if a compile job, has one primary swift input
   /// May return empty if none.
   StringRef getFirstSwiftPrimaryInput() const;
+
+#ifndef NDEBUG
+  unsigned getWave() const { return Wave; }
+  void setWave(unsigned WaveNum) const { Wave = WaveNum; }
+#endif
 };
 
 /// A BatchJob comprises a _set_ of jobs, each of which is sufficiently similar

lib/Driver/Compilation.cpp

@@ -323,6 +323,17 @@ namespace driver {
         return;
       }
 
+#ifndef NDEBUG
+      // If we can, assert that no compile jobs are scheduled beyond the second
+      // wave. If this assertion fails, it indicates one of:
+      // 1) A failure of the driver's job tracing machinery to follow a
+      // dependency arc.
+      // 2) A failure of the frontend to emit a dependency arc.
+      if (isa<CompileJobAction>(Cmd->getSource()) && Cmd->getWave() > 2) {
+        llvm_unreachable("Scheduled a command into a third wave!");
+      }
+#endif
+
       // Adding to scheduled means we've committed to its completion (not
       // distinguished from skipping). We never remove it once inserted.
       ScheduledCommands.insert(Cmd);
@@ -694,8 +705,16 @@ namespace driver {
                        "because of dependencies discovered later");
 
       scheduleCommandsInSortedOrder(DependentsInEffect);
-      for (const Job *Cmd : DependentsInEffect)
-        DeferredCommands.erase(Cmd);
+      for (const Job *Cmd : DependentsInEffect) {
+        if (DeferredCommands.erase(Cmd)) {
+#ifndef NDEBUG
+          if (isa<CompileJobAction>(FinishedCmd->getSource()))
+            Cmd->setWave(FinishedCmd->getWave() + 1);
+#else
+          continue;
+#endif
+        }
+      }
       return TaskFinishedResponse::ContinueExecution;
     }