Merge remote-tracking branch 'upstream/master' into ca-drv-exotic

1 files changed, 128 insertions, 59 deletions

diff --git a/src/libstore/build/worker.hh b/src/libstore/build/worker.hh
index 6d68d3cf1..48a1a27fa 100644
--- a/src/libstore/build/worker.hh
+++ b/src/libstore/build/worker.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "lock.hh"
@@ -16,24 +17,29 @@ struct DerivationGoal;
 struct PathSubstitutionGoal;
 class DrvOutputSubstitutionGoal;
 
-/* Workaround for not being able to declare a something like
-
-     class PathSubstitutionGoal : public Goal;
-
-   even when Goal is a complete type.
-
-   This is still a static cast. The purpose of exporting it is to define it in
-   a place where `PathSubstitutionGoal` is concrete, and use it in a place where it
-   is opaque. */
+/**
+ * Workaround for not being able to declare a something like
+ *
+ * ```c++
+ * class PathSubstitutionGoal : public Goal;
+ * ```
+ * even when Goal is a complete type.
+ *
+ * This is still a static cast. The purpose of exporting it is to define it in
+ * a place where `PathSubstitutionGoal` is concrete, and use it in a place where it
+ * is opaque.
+ */
 GoalPtr upcast_goal(std::shared_ptr<PathSubstitutionGoal> subGoal);
 GoalPtr upcast_goal(std::shared_ptr<DrvOutputSubstitutionGoal> subGoal);
 
 typedef std::chrono::time_point<std::chrono::steady_clock> steady_time_point;
 
 
-/* A mapping used to remember for each child process to what goal it
-   belongs, and file descriptors for receiving log data and output
-   path creation commands. */
+/**
+ * A mapping used to remember for each child process to what goal it
+ * belongs, and file descriptors for receiving log data and output
+ * path creation commands.
+ */
 struct Child
 {
     WeakGoalPtr goal;
@@ -41,14 +47,19 @@ struct Child
     std::set<int> fds;
     bool respectTimeouts;
     bool inBuildSlot;
-    steady_time_point lastOutput; /* time we last got output on stdout/stderr */
+    /**
+     * Time we last got output on stdout/stderr
+     */
+    steady_time_point lastOutput;
     steady_time_point timeStarted;
 };
 
 /* Forward definition. */
 struct HookInstance;
 
-/* The worker class. */
+/**
+ * The worker class.
+ */
 class Worker
 {
 private:
@@ -56,38 +67,58 @@ private:
     /* Note: the worker should only have strong pointers to the
        top-level goals. */
 
-    /* The top-level goals of the worker. */
+    /**
+     * The top-level goals of the worker.
+     */
     Goals topGoals;
 
-    /* Goals that are ready to do some work. */
+    /**
+     * Goals that are ready to do some work.
+     */
     WeakGoals awake;
 
-    /* Goals waiting for a build slot. */
+    /**
+     * Goals waiting for a build slot.
+     */
     WeakGoals wantingToBuild;
 
-    /* Child processes currently running. */
+    /**
+     * Child processes currently running.
+     */
     std::list<Child> children;
 
-    /* Number of build slots occupied.  This includes local builds and
-       substitutions but not remote builds via the build hook. */
+    /**
+     * Number of build slots occupied.  This includes local builds and
+     * substitutions but not remote builds via the build hook.
+     */
     unsigned int nrLocalBuilds;
 
-    /* Maps used to prevent multiple instantiations of a goal for the
-       same derivation / path. */
+    /**
+     * Maps used to prevent multiple instantiations of a goal for the
+     * same derivation / path.
+     */
     std::map<StorePath, std::weak_ptr<DerivationGoal>> derivationGoals;
     std::map<StorePath, std::weak_ptr<PathSubstitutionGoal>> substitutionGoals;
     std::map<DrvOutput, std::weak_ptr<DrvOutputSubstitutionGoal>> drvOutputSubstitutionGoals;
 
-    /* Goals waiting for busy paths to be unlocked. */
+    /**
+     * Goals waiting for busy paths to be unlocked.
+     */
     WeakGoals waitingForAnyGoal;
 
-    /* Goals sleeping for a few seconds (polling a lock). */
+    /**
+     * Goals sleeping for a few seconds (polling a lock).
+     */
     WeakGoals waitingForAWhile;
 
-    /* Last time the goals in `waitingForAWhile' where woken up. */
+    /**
+     * Last time the goals in `waitingForAWhile` where woken up.
+     */
     steady_time_point lastWokenUp;
 
-    /* Cache for pathContentsGood(). */
+    /**
+     * Cache for pathContentsGood().
+     */
     std::map<StorePath, bool> pathContentsGoodCache;
 
 public:
@@ -96,17 +127,25 @@ public:
     const Activity actDerivations;
     const Activity actSubstitutions;
 
-    /* Set if at least one derivation had a BuildError (i.e. permanent
-       failure). */
+    /**
+     * Set if at least one derivation had a BuildError (i.e. permanent
+     * failure).
+     */
     bool permanentFailure;
 
-    /* Set if at least one derivation had a timeout. */
+    /**
+     * Set if at least one derivation had a timeout.
+     */
     bool timedOut;
 
-    /* Set if at least one derivation fails with a hash mismatch. */
+    /**
+     * Set if at least one derivation fails with a hash mismatch.
+     */
     bool hashMismatch;
 
-    /* Set if at least one derivation is not deterministic in check mode. */
+    /**
+     * Set if at least one derivation is not deterministic in check mode.
+     */
     bool checkMismatch;
 
     Store & store;
@@ -128,16 +167,22 @@ public:
     uint64_t expectedNarSize = 0;
     uint64_t doneNarSize = 0;
 
-    /* Whether to ask the build hook if it can build a derivation. If
-       it answers with "decline-permanently", we don't try again. */
+    /**
+     * Whether to ask the build hook if it can build a derivation. If
+     * it answers with "decline-permanently", we don't try again.
+     */
     bool tryBuildHook = true;
 
     Worker(Store & store, Store & evalStore);
     ~Worker();
 
-    /* Make a goal (with caching). */
+    /**
+     * Make a goal (with caching).
+     */
 
-    /* derivation goal */
+    /**
+     * derivation goal
+     */
 private:
     std::shared_ptr<DerivationGoal> makeDerivationGoalCommon(
         const StorePath & drvPath, const OutputsSpec & wantedOutputs,
@@ -150,56 +195,80 @@ public:
         const StorePath & drvPath, const BasicDerivation & drv,
         const OutputsSpec & wantedOutputs, BuildMode buildMode = bmNormal);
 
-    /* substitution goal */
+    /**
+     * substitution goal
+     */
     std::shared_ptr<PathSubstitutionGoal> makePathSubstitutionGoal(const StorePath & storePath, RepairFlag repair = NoRepair, std::optional<ContentAddress> ca = std::nullopt);
     std::shared_ptr<DrvOutputSubstitutionGoal> makeDrvOutputSubstitutionGoal(const DrvOutput & id, RepairFlag repair = NoRepair, std::optional<ContentAddress> ca = std::nullopt);
 
-    /* Remove a dead goal. */
+    /**
+     * Remove a dead goal.
+     */
     void removeGoal(GoalPtr goal);
 
-    /* Wake up a goal (i.e., there is something for it to do). */
+    /**
+     * Wake up a goal (i.e., there is something for it to do).
+     */
     void wakeUp(GoalPtr goal);
 
-    /* Return the number of local build and substitution processes
-       currently running (but not remote builds via the build
-       hook). */
+    /**
+     * Return the number of local build and substitution processes
+     * currently running (but not remote builds via the build
+     * hook).
+     */
     unsigned int getNrLocalBuilds();
 
-    /* Registers a running child process.  `inBuildSlot' means that
-       the process counts towards the jobs limit. */
+    /**
+     * Registers a running child process.  `inBuildSlot` means that
+     * the process counts towards the jobs limit.
+     */
     void childStarted(GoalPtr goal, const std::set<int> & fds,
         bool inBuildSlot, bool respectTimeouts);
 
-    /* Unregisters a running child process.  `wakeSleepers' should be
-       false if there is no sense in waking up goals that are sleeping
-       because they can't run yet (e.g., there is no free build slot,
-       or the hook would still say `postpone'). */
+    /**
+     * Unregisters a running child process.  `wakeSleepers` should be
+     * false if there is no sense in waking up goals that are sleeping
+     * because they can't run yet (e.g., there is no free build slot,
+     * or the hook would still say `postpone`).
+     */
     void childTerminated(Goal * goal, bool wakeSleepers = true);
 
-    /* Put `goal' to sleep until a build slot becomes available (which
-       might be right away). */
+    /**
+     * Put `goal` to sleep until a build slot becomes available (which
+     * might be right away).
+     */
     void waitForBuildSlot(GoalPtr goal);
 
-    /* Wait for any goal to finish.  Pretty indiscriminate way to
-       wait for some resource that some other goal is holding. */
+    /**
+     * Wait for any goal to finish.  Pretty indiscriminate way to
+     * wait for some resource that some other goal is holding.
+     */
     void waitForAnyGoal(GoalPtr goal);
 
-    /* Wait for a few seconds and then retry this goal.  Used when
-       waiting for a lock held by another process.  This kind of
-       polling is inefficient, but POSIX doesn't really provide a way
-       to wait for multiple locks in the main select() loop. */
+    /**
+     * Wait for a few seconds and then retry this goal.  Used when
+     * waiting for a lock held by another process.  This kind of
+     * polling is inefficient, but POSIX doesn't really provide a way
+     * to wait for multiple locks in the main select() loop.
+     */
     void waitForAWhile(GoalPtr goal);
 
-    /* Loop until the specified top-level goals have finished. */
+    /**
+     * Loop until the specified top-level goals have finished.
+     */
     void run(const Goals & topGoals);
 
-    /* Wait for input to become available. */
+    /**
+     * Wait for input to become available.
+     */
     void waitForInput();
 
     unsigned int exitStatus();
 
-    /* Check whether the given valid path exists and has the right
-       contents. */
+    /**
+     * Check whether the given valid path exists and has the right
+     * contents.
+     */
     bool pathContentsGood(const StorePath & path);
 
     void markContentsGood(const StorePath & path);