Make OccupiedGraphNode value page-able via PagableNodeValue

cjhopman · meta-codesync[bot] · commit 6d219209ba5a · 2026-04-28T19:54:01.000-07:00
Summary:
Introduces a `PagableNodeValue` enum (`Hydrated(DiceValidValue)` / `PagedOut(DataKey)`)
and stores it as `OccupiedGraphNode.res`. Adds two new `VersionedGraphResult`
variants — `MatchPagedOut(PagedOutMatch)` and `CheckDepsPagedOut(PagedOutMismatch)`
— that the graph emits when the node's value is paged out, carrying the `DataKey`
the worker needs to hydrate.

`OccupiedGraphNode::val()` now returns `&amp;PagableNodeValue`; callers needing the
hydrated value call `.expect_hydrated(msg)` with a message explaining why they
know the value is hydrated (analogous to `Option::expect`).

No code path actually constructs `PagableNodeValue::PagedOut` yet, so the new
lookup variants are unreachable in practice. The follow-up commit wires up
`Dice::page_out` (which transitions nodes to `PagedOut`) and the worker
hydration step (which consumes the new variants).

Tests pass unchanged.

Reviewed By: jtbraun

Differential Revision: D101759758

fbshipit-source-id: 2efd54a402bc01aecc3f3c62d8de7d622c70fc67
diff --git a/dice/dice/src/impls/core/graph/nodes.rs b/dice/dice/src/impls/core/graph/nodes.rs
@@ -25,8 +25,11 @@ use allocative::Allocative;
 use dupe::Dupe;
 use gazebo::variants::UnpackVariants;
 use itertools::Itertools;
+use pagable::DataKey;
 use sorted_vector_map::SortedVectorMap;
 
+use super::types::PagedOutMatch;
+use super::types::PagedOutMismatch;
 use super::types::VersionedGraphResult;
 use crate::HashSet;
 use crate::api::key::InvalidationSourcePriority;
@@ -162,7 +165,10 @@ impl VersionedGraphNode {
             VersionedGraphNode::Occupied(entry) if reusable.is_reusable(&value, &deps, entry) => {
                 debug!("marking graph entry as unchanged");
                 entry.mark_unchanged(key.v, valid_deps_versions, invalidation_paths);
-                let ret = entry.computed_val(key.v);
+                let ret = entry.computed_val(
+                    key.v,
+                    "is_reusable returned true, which only happens for hydrated entries",
+                );
                 return (ret, false);
             }
             VersionedGraphNode::Occupied(entry) => {
@@ -214,7 +220,10 @@ impl VersionedGraphNode {
             dirtied_history.clone(),
             invalidation_paths,
         );
-        let ret = new.computed_val(key.v);
+        let ret = new.computed_val(
+            key.v,
+            "newly-constructed OccupiedGraphNode is always hydrated",
+        );
         *self = VersionedGraphNode::Occupied(new);
 
         (ret, true)
@@ -298,11 +307,52 @@ pub(crate) enum InvalidateResult<'a> {
     Changed(Option<std::vec::Drain<'a, DiceKey>>),
 }
 
+/// The stored value for an `OccupiedGraphNode`. At least one of `value` (the
+/// in-memory hydrated form) and `data_key` (the on-disk content-addressable
+/// reference) must be set. When both are set, the value is resident in memory
+/// AND known to be persisted on disk, so the next page-out can skip
+/// re-serialization.
+#[derive(Allocative, Debug)]
+pub(crate) struct PagableNodeValue {
+    value: Option<DiceValidValue>,
+    data_key: Option<DataKey>,
+}
+
+impl PagableNodeValue {
+    /// Constructs a hydrated-only value (no on-disk copy yet).
+    pub(crate) fn hydrated(value: DiceValidValue) -> Self {
+        Self {
+            value: Some(value),
+            data_key: None,
+        }
+    }
+
+    /// Returns the hydrated value, panicking with `msg` if the value is not currently
+    /// resident in memory. `msg` should explain why the caller knows the value is
+    /// hydrated (analogous to `Option::expect`).
+    pub(crate) fn expect_hydrated(&self, msg: &str) -> &DiceValidValue {
+        self.value.as_ref().unwrap_or_else(|| {
+            panic!(
+                "PagableNodeValue::expect_hydrated called on a paged-out value: {}",
+                msg
+            )
+        })
+    }
+
+    #[expect(
+        dead_code,
+        reason = "used by the page-out flow; D101759759 will remove this suppression"
+    )]
+    pub(crate) fn as_hydrated(&self) -> Option<&DiceValidValue> {
+        self.value.as_ref()
+    }
+}
+
 /// The stored entry of the cache
 #[derive(Allocative, Debug)]
 pub(crate) struct OccupiedGraphNode {
     key: DiceKey,
-    res: DiceValidValue,
+    res: PagableNodeValue,
     metadata: NodeMetadata,
     invalidation_paths: TrackedInvalidationPaths,
 }
@@ -436,7 +486,7 @@ impl OccupiedGraphNode {
     ) -> Self {
         Self {
             key,
-            res,
+            res: PagableNodeValue::hydrated(res),
             metadata: NodeMetadata {
                 deps,
                 rdeps: LazyDepsSet::new(),
@@ -467,13 +517,33 @@ impl OccupiedGraphNode {
         self.invalidation_paths.update(new_invalidation_paths)
     }
 
-    pub(crate) fn val(&self) -> &DiceValidValue {
+    /// Returns this node's stored value (which may be hydrated or paged out).
+    /// Callers that need a hydrated `DiceValidValue` should call `.expect_hydrated(msg)`
+    /// with a message explaining why the caller knows the value is hydrated.
+    pub(crate) fn val(&self) -> &PagableNodeValue {
         &self.res
     }
 
-    pub(crate) fn computed_val(&self, for_version: VersionNumber) -> DiceComputedValue {
+    /// Restores the in-memory hydrated value (typically after deserializing from
+    /// disk). Keeps any existing `data_key` so the next page-out skips
+    /// re-serialization.
+    #[expect(
+        dead_code,
+        reason = "used by the rehydrate request; D101759759 will remove this suppression"
+    )]
+    pub(crate) fn rehydrate(&mut self, value: DiceValidValue) {
+        self.res.value = Some(value);
+    }
+
+    /// `expect_hydrated_msg` is forwarded to `expect_hydrated` and should explain why the
+    /// caller knows the entry is hydrated.
+    pub(crate) fn computed_val(
+        &self,
+        for_version: VersionNumber,
+        expect_hydrated_msg: &str,
+    ) -> DiceComputedValue {
         DiceComputedValue::new(
-            MaybeValidDiceValue::valid(self.res.dupe()),
+            MaybeValidDiceValue::valid(self.val().expect_hydrated(expect_hydrated_msg).dupe()),
             self.metadata.verified_ranges.dupe(),
             self.invalidation_paths.at_version(for_version),
         )
@@ -487,13 +557,20 @@ impl OccupiedGraphNode {
     ) -> InvalidateResult<'_> {
         // TODO(cjhopman): accepting injections only for InjectedKey would make the VersionedGraph simpler. Currently, this is used
         // for "mocking" dice keys in tests via DiceBuilder::mock_and_return().
-        if self.val().equality(&value) {
+        if self
+            .val()
+            .expect_hydrated(
+                "on_injected does not yet handle paged-out entries; this is a known \
+                 footgun fixed in a follow-up commit",
+            )
+            .equality(&value)
+        {
             // TODO(cjhopman): This is wrong. The node could currently be in a dirtied state and we
             // aren't recording that the value is verified at this version.
             return InvalidateResult::NoChange;
         }
 
-        self.res = value;
+        self.res = PagableNodeValue::hydrated(value);
         self.metadata.deps = Arc::new(SeriesParallelDeps::None);
         self.metadata.verified_ranges = Arc::new(VersionRange::begins_with(version).into_ranges());
         self.invalidation_paths
@@ -508,19 +585,43 @@ impl OccupiedGraphNode {
 
     fn at_version(&self, v: VersionNumber) -> VersionedGraphResult {
         match self.metadata.verified_ranges.find_value_upper_bound(v) {
-            Some(found) if found == v => VersionedGraphResult::Match(self.computed_val(v)),
+            Some(found) if found == v => {
+                if self.res.value.is_some() {
+                    VersionedGraphResult::Match(
+                        self.computed_val(v, "the Hydrated branch checked value.is_some()"),
+                    )
+                } else {
+                    VersionedGraphResult::MatchPagedOut(PagedOutMatch {
+                        data_key: self.res.data_key.expect(
+                            "PagableNodeValue invariant: at least one of value or data_key is set",
+                        ),
+                        valid: self.metadata.verified_ranges.dupe(),
+                        invalidation_paths: self.invalidation_paths.at_version(v),
+                    })
+                }
+            }
             Some(prev_verified_version) => {
                 if self
                     .metadata
                     .dirtied_history
                     .restricted_range(v)
                     .contains(&prev_verified_version)
                 {
-                    VersionedGraphResult::CheckDeps(VersionedGraphResultMismatch {
-                        entry: self.val().dupe(),
-                        prev_verified_version,
-                        deps_to_validate: self.metadata.deps.dupe(),
-                    })
+                    if let Some(value) = &self.res.value {
+                        VersionedGraphResult::CheckDeps(VersionedGraphResultMismatch {
+                            entry: value.dupe(),
+                            prev_verified_version,
+                            deps_to_validate: self.metadata.deps.dupe(),
+                        })
+                    } else {
+                        VersionedGraphResult::CheckDepsPagedOut(PagedOutMismatch {
+                            data_key: self.res.data_key.expect(
+                                "PagableNodeValue invariant: at least one of value or data_key is set",
+                            ),
+                            prev_verified_version,
+                            deps_to_validate: self.metadata.deps.dupe(),
+                        })
+                    }
                 } else {
                     VersionedGraphResult::Compute
                 }
diff --git a/dice/dice/src/impls/core/graph/storage.rs b/dice/dice/src/impls/core/graph/storage.rs
@@ -365,7 +365,7 @@ impl VersionedGraph {
             invalidation_paths,
         );
 
-        let res = entry.computed_val(v);
+        let res = entry.computed_val(v, "newly-constructed OccupiedGraphNode is always hydrated");
         self.nodes.insert(key, VersionedGraphNode::Occupied(entry));
         res
     }
@@ -407,7 +407,11 @@ impl ValueReusable {
                 if new_deps != &***value.deps() {
                     return false;
                 }
-                new_value.equality(value.val())
+                new_value.equality(value.val().expect_hydrated(
+                    "is_reusable: no node is paged out at this point in the stack \
+                     (page_out is wired up in a follow-up commit); the paged-out case \
+                     is fixed there to return false instead",
+                ))
             }
             // For version-based, the deps are guaranteed to match if `version` is in the node's verified versions.
             ValueReusable::VersionBased(version) => value.is_verified_at(*version),
diff --git a/dice/dice/src/impls/core/graph/types.rs b/dice/dice/src/impls/core/graph/types.rs
@@ -13,13 +13,16 @@
 use dupe::Dupe;
 use gazebo::variants::UnpackVariants;
 use gazebo::variants::VariantName;
+use pagable::DataKey;
 
 use crate::arc::Arc;
 use crate::impls::deps::graph::SeriesParallelDeps;
 use crate::impls::key::DiceKey;
 use crate::impls::value::DiceComputedValue;
 use crate::impls::value::DiceValidValue;
+use crate::impls::value::TrackedInvalidationPaths;
 use crate::versions::VersionNumber;
+use crate::versions::VersionRanges;
 
 /// The Key for a Versioned, incremental computation
 #[derive(Copy, Clone, Dupe, Debug)]
@@ -43,13 +46,54 @@ pub(crate) struct VersionedGraphResultMismatch {
     pub(crate) deps_to_validate: Arc<SeriesParallelDeps>,
 }
 
+/// Equivalent of [`DiceComputedValue`] for the case where the matched entry's value is
+/// paged out. The worker hydrates `data_key` via `DiceStorage` to materialize the value
+/// before constructing a `DiceComputedValue`.
+#[derive(Debug)]
+#[expect(
+    dead_code,
+    reason = "fields consumed by the worker; D101759759 will remove this suppression"
+)]
+pub(crate) struct PagedOutMatch {
+    pub(crate) data_key: DataKey,
+    pub(crate) valid: Arc<VersionRanges>,
+    pub(crate) invalidation_paths: TrackedInvalidationPaths,
+}
+
+/// Equivalent of [`VersionedGraphResultMismatch`] for the case where the previous entry's
+/// value is paged out. The worker hydrates `data_key` via `DiceStorage` to materialize the
+/// previous value before deciding whether deps still hold.
+#[derive(Debug)]
+#[expect(
+    dead_code,
+    reason = "fields consumed by the worker; D101759759 will remove this suppression"
+)]
+pub(crate) struct PagedOutMismatch {
+    pub(crate) data_key: DataKey,
+    pub(crate) prev_verified_version: VersionNumber,
+    pub(crate) deps_to_validate: Arc<SeriesParallelDeps>,
+}
+
 #[derive(Debug, VariantName, UnpackVariants)]
 pub(crate) enum VersionedGraphResult {
     /// the entry is present and valid at the requested version
     Match(DiceComputedValue),
+    /// the entry is present and valid at the requested version, but its value is paged
+    /// out and must be hydrated before use
+    #[expect(
+        dead_code,
+        reason = "constructed when paging actually happens; D101759759 will remove this suppression"
+    )]
+    MatchPagedOut(PagedOutMatch),
     /// the entry at the requested version has been invalidated and
     /// we have a previous value with deps to possibly resurrect
     CheckDeps(VersionedGraphResultMismatch),
+    /// like `CheckDeps`, but the previous entry's value is paged out
+    #[expect(
+        dead_code,
+        reason = "constructed when paging actually happens; D101759759 will remove this suppression"
+    )]
+    CheckDepsPagedOut(PagedOutMismatch),
     /// the entry is missing or there's no previously valid value to check
     Compute,
     /// the storage has rejected the request
diff --git a/dice/dice/src/impls/worker.rs b/dice/dice/src/impls/worker.rs
@@ -161,7 +161,15 @@ impl DiceTaskWorker {
             VersionedGraphResult::Match(entry) => {
                 return task_state.lookup_matches(handle, entry);
             }
+            VersionedGraphResult::MatchPagedOut(_) => {
+                // Page-in is wired up in a follow-up commit. Until then, no node ever
+                // ends up paged out (see DiceStorage), so this branch is unreachable.
+                unreachable!("paged-out lookup result not yet supported by worker")
+            }
             VersionedGraphResult::CheckDeps(mismatch2) => Some(mismatch2),
+            VersionedGraphResult::CheckDepsPagedOut(_) => {
+                unreachable!("paged-out lookup result not yet supported by worker")
+            }
             VersionedGraphResult::Compute => None,
             VersionedGraphResult::Rejected(..) => {
                 return Err(CancellationReason::Rejected);
