Introduce `SingleDrvOutputs`

In many cases we are dealing with a collection of realisations, they are
all outputs of the same derivation. In that case, we don't need
"derivation hashes modulos" to be part of our map key, because the
output names alone will be unique. Those hashes are still part of the
realisation proper, so we aren't loosing any information, we're just
"normalizing our schema" by narrowing the "primary key".

Besides making our data model a bit "tighter" this allows us to avoid a
double `for` loop in `DerivationGoal::waiteeDone`. The inner `for` loop
was previously just to select the output we cared about without knowing
its hash. Now we can just select the output by name directly.

Note that neither protocol is changed as part of this: we are still
transferring `DrvOutputs` over the wire for `BuildResult`s. I would only
consider revising this once #6223 is merged, and we can mention protocol
versions inside factored-out serialization logic. Until then it is
better not change anything because it would come a the cost of code
reuse.

1 files changed, 32 insertions, 1 deletions

diff --git a/src/libstore/realisation.hh b/src/libstore/realisation.hh
index a18cf2aa8..3922d1267 100644
--- a/src/libstore/realisation.hh
+++ b/src/libstore/realisation.hh
@@ -13,9 +13,25 @@ namespace nix {
 
 class Store;
 
+/**
+ * A general `Realisation` key.
+ *
+ * This is similar to a `DerivedPath::Opaque`, but the derivation is
+ * identified by its "hash modulo" instead of by its store path.
+ */
 struct DrvOutput {
-    // The hash modulo of the derivation
+    /**
+     * The hash modulo of the derivation.
+     *
+     * Computed from the derivation itself for most types of
+     * derivations, but computed from the (fixed) content address of the
+     * output for fixed-output derivations.
+     */
     Hash drvHash;
+
+    /**
+     * The name of the output.
+     */
     std::string outputName;
 
     std::string to_string() const;
@@ -60,6 +76,21 @@ struct Realisation {
     GENERATE_CMP(Realisation, me->id, me->outPath);
 };
 
+/**
+ * Collection type for a single derivation's outputs' `Realisation`s.
+ *
+ * Since these are the outputs of a single derivation, we know the
+ * output names are unique so we can use them as the map key.
+ */
+typedef std::map<std::string, Realisation> SingleDrvOutputs;
+
+/**
+ * Collection type for multiple derivations' outputs' `Realisation`s.
+ *
+ * `DrvOutput` is used because in general the derivations are not all
+ * the same, so we need to identify firstly which derivation, and
+ * secondly which output of that derivation.
+ */
 typedef std::map<DrvOutput, Realisation> DrvOutputs;
 
 struct OpaquePath {