.

Author: lihaoyi

core/api/daemon/src/mill/api/daemon/internal/LauncherLocking.scala

@@ -2,6 +2,13 @@ package mill.api.daemon.internal
 
 import java.nio.file.Path
 
+/**
+ * Locking APIs to let us safely run multiple concurrent launchers at the same time
+ *
+ * [[metaBuildLock]] ensures that only one launcher can be bootstrapping the meta-build,
+ * but once the meta-build is done multiple launchers can run concurrently and only lock
+ * on the individual tasks they need to run or use.
+ */
 private[mill] trait LauncherLocking extends AutoCloseable {
 
   def metaBuildLock(depth: Int, kind: LauncherLocking.LockKind): LauncherLocking.Lease
@@ -18,8 +25,6 @@ private[mill] object LauncherLocking {
     case Read, Write
   }
 
-  final case class HolderInfo(pid: Long, command: String)
-
   trait Lease extends AutoCloseable {
     def downgradeToRead(): Unit = ()
   }

core/api/daemon/src/mill/api/daemon/internal/bsp/BspBootstrapBridge.scala

@@ -2,9 +2,11 @@ package mill.api.daemon.internal.bsp
 
 import scala.concurrent.Future
 
+/** With this server handle you can interact with a running Mill BSP server. */
 trait BspServerHandle {
 
   /**
+   * Completes when the BSP server shuts down or asks the launcher to reload the workspace.
    */
   def shutdownFuture: Future[BspServerResult]
 

core/api/daemon/src/mill/api/daemon/internal/bsp/BspServerHandle.scala

@@ -306,6 +306,7 @@ object Task {
    *
    * Like [[PersistentImpl]], The user defining a [[Worker]] assumes the
    * responsibility of ensuring the implementation is idempotent regardless of
+   * what in-memory state the worker may have.
    */
   inline def Worker[T](inline t: Result[T])(using inline ctx: mill.api.ModuleCtx): Worker[T] =
     ${ Macros.workerImpl2[T]('t)('ctx) }

core/api/src/mill/api/Task.scala

@@ -29,10 +29,13 @@ public class EnvVars {
 
   /**
    * Output directory where Mill workers' state and Mill tasks output should be
+   * written to in BSP server mode.
    */
   public static final String MILL_BSP_OUTPUT_DIR = "MILL_BSP_OUTPUT_DIR";
 
   /**
+   * If set to "1", Mill will re-use the regular out/ folder instead of
+   * using a separate one for BSP output.
    */
   public static final String MILL_NO_SEPARATE_BSP_OUTPUT_DIR = "MILL_NO_SEPARATE_BSP_OUTPUT_DIR";
 

core/constants/src/mill/constants/EnvVars.java

@@ -35,6 +35,8 @@ private OutFiles1() {}
     public final String defaultOut = "out";
 
     /**
+     * Default hard-coded value for the Mill `out/` folder path in BSP server mode.
+     * To get the effective out dir, use {@link #outFor}.
      */
     public final String defaultBspOut = ".bsp/out";
 
@@ -193,6 +195,7 @@ public static String outFor(OutFolderMode outMode) {
   /** @deprecated Use inner OutFiles instead, since Mill 1.1.0 */
   @Deprecated
   public static final String millOutLock = OutFiles.millOutLock;
+  /** @deprecated Use inner OutFiles instead, since Mill 1.1.0 */
   @Deprecated
   public static final String millActive = "mill-active.json";
   /** @deprecated Use millActive instead */

core/constants/src/mill/constants/OutFiles.java

@@ -295,6 +295,11 @@ case class Execution(
             ec.fold(ExecutionContexts.RunNow)(new ExecutionContexts.ThreadPool(_))
           implicit val taskExecutionContext =
             if (exclusive) ExecutionContexts.RunNow else forkExecutionContext
+          // We walk the task graph in topological order and schedule the futures
+          // to run asynchronously. During this walk, we store the scheduled futures
+          // in a dictionary. When scheduling each future, we are guaranteed that the
+          // necessary upstream futures will have already been scheduled and stored,
+          // due to the topological order of traversal.
           for (terminal <- terminals) {
             val deps = interGroupDeps(terminal)
 
@@ -376,9 +381,11 @@ case class Execution(
 
                       val newFailures = res.newResults.values.count(r => r.asFailing.isDefined)
 
+                      // Count new failures: tasks with upstream failures should be skipped, not failed.
                       rootFailedCount.addAndGet(newFailures)
                       completedCount.incrementAndGet()
 
+                      // Always show the completed count in the header after a task finishes.
                       logger.prompt.setPromptHeaderPrefix(formatHeaderPrefix())
 
                       if (failFast && res.newResults.values.exists(_.asSuccess.isEmpty))
@@ -404,9 +411,14 @@ case class Execution(
                     }
                   }
                 } catch {
-                  case e: mill.api.daemon.StopWithResponse[?] => throw e
+                  case e: mill.api.daemon.StopWithResponse[?] =>
+                    // Let StopWithResponse propagate: it is a controlled shutdown signal.
+                    throw e
                   case e: Throwable if !mill.api.daemon.internal.NonFatal(e) =>
+                    // Wrap fatal errors so Scala's Future machinery reports them instead of
+                    // silently terminating the future and leaving downstream Awaits hanging.
                     val nonFatal = new Exception(s"fatal exception occurred: $e", e)
+                    // Preserve the original stack trace, since that points at the real failure.
                     nonFatal.setStackTrace(e.getStackTrace)
                     throw nonFatal
                 } finally {
@@ -416,9 +428,13 @@ case class Execution(
             }
           }
 
+          // Make sure we wait for all tasks from this batch to finish before starting the next
+          // one, so we don't mix up exclusive and non-exclusive tasks running at the same time.
           terminals.map(t => (t, Await.result(futures(t), duration.Duration.Inf)))
         }
 
+        // Run all non-command tasks according to the configured thread count,
+        // but run exclusive commands in linear order.
         val (nonExclusiveTasks, leafExclusiveCommands) = indexToTerminal.partition {
           case t: Task.Named[_] => !downstreamOfExclusive.contains(t)
           case _ => !serialCommandExec
@@ -431,13 +447,17 @@ case class Execution(
         val isOutermostExecution = executionNestingDepth.get() == 1
         val hasFailures = rootFailedCount.get() > 0
         val showFinalStatus = isOutermostExecution && (hasFailures || isFinalDepth)
+        // Set final header showing SUCCESS/FAILED status:
+        // - FAILED: show for any outermost execution with failures
+        // - SUCCESS: only show for the final requested depth
         logger.prompt.setPromptHeaderPrefix(formatHeaderPrefix(completed = showFinalStatus))
 
         logger.prompt.clearPromptStatuses()
 
         val finishedOptsMap = (nonExclusiveResults ++ exclusiveResults).toMap
 
         val taskInvalidationReasons = {
+          // Convert versionMismatchReasons to Map[String, String] for invalidation-tree logging.
           import scala.jdk.CollectionConverters.ConcurrentMapHasAsScala
           versionMismatchReasons.asScala.collect {
             case (t: Task.Named[?], reason) => t.ctx.segments.render -> reason

core/exec/src/mill/exec/Execution.scala

@@ -40,7 +40,9 @@ object ExecutionContexts {
 
     override def compareTo(other: QueuedRunnable): Int =
       priority.compareTo(other.priority) match {
-        case 0 => submissionIndex.compareTo(other.submissionIndex)
+        case 0 =>
+          // Comparable needs a total ordering, so break ties using submission order.
+          submissionIndex.compareTo(other.submissionIndex)
         case n => n
       }
   }

core/exec/src/mill/exec/ExecutionContexts.scala

@@ -309,6 +309,8 @@ trait GroupExecution {
               logger = logger,
               inputsHash = inputsHash,
               labelled = labelled,
+              // `cached.isEmpty` means the worker metadata file was removed by the user,
+              // so recompute the worker.
               forceDiscard = cached.isEmpty,
               deps = deps,
               paths = Some(paths),
@@ -405,6 +407,10 @@ trait GroupExecution {
                     (valueHash, serializedPaths, true)
 
                   case _ =>
+                    // Wipe out any cached meta.json file that exists, so
+                    // a following run won't look at the cached metadata file and
+                    // assume it's associated with the possibly-borked state of the
+                    // destPath after an evaluation failure.
                     os.remove.all(paths.meta)
                     (0, Nil, false)
                 }

core/exec/src/mill/exec/GroupExecution.scala

@@ -1,7 +1,7 @@
 package mill.internal
 
 import mill.api.daemon.internal.LauncherLocking
-import mill.api.daemon.internal.LauncherLocking.HolderInfo
+import mill.internal.WriterPreferringRwLock.HolderInfo
 
 import java.io.PrintStream
 import java.util.concurrent.atomic.AtomicBoolean