diff --git a/nix-bindings-expr/src/eval_state.rs b/nix-bindings-expr/src/eval_state.rs index 138b3be..c05ae9b 100644 --- a/nix-bindings-expr/src/eval_state.rs +++ b/nix-bindings-expr/src/eval_state.rs @@ -442,6 +442,8 @@ impl EvalState { /// Converts [thunks](https://nix.dev/manual/nix/latest/language/evaluation.html#laziness) to their evaluated form. Does not modify already-evaluated values. /// /// Does not perform deep evaluation of nested structures. + /// + /// See also: [Shared Evaluation State](Value#shared-evaluation-state) #[doc(alias = "evaluate")] #[doc(alias = "strict")] pub fn force(&mut self, v: &Value) -> Result<()> { @@ -460,6 +462,8 @@ impl EvalState { /// Returns [`None`] if the value is an unevaluated [thunk](https://nix.dev/manual/nix/latest/language/evaluation.html#laziness). /// /// Returns [`Some`] if the value is already evaluated. + /// + /// See also: [Shared Evaluation State](Value#shared-evaluation-state) #[doc(alias = "type_of")] #[doc(alias = "value_type_lazy")] #[doc(alias = "nix_get_type")] diff --git a/nix-bindings-expr/src/value.rs b/nix-bindings-expr/src/value.rs index e75c4df..68bb444 100644 --- a/nix-bindings-expr/src/value.rs +++ b/nix-bindings-expr/src/value.rs @@ -65,6 +65,21 @@ impl ValueType { } /// A pointer to a [value](https://nix.dev/manual/nix/latest/language/types.html) or [thunk](https://nix.dev/manual/nix/2.31/language/evaluation.html?highlight=thunk#laziness), to be used with [`EvalState`][`crate::eval_state::EvalState`] methods. +/// +/// # Shared Evaluation State +/// +/// Multiple `Value` instances can reference the same underlying Nix value. +/// This occurs when a `Value` is [cloned](Clone), or when multiple Nix +/// expressions reference the same binding. +/// +/// When any reference to a thunk is evaluated—whether through +/// [`force`](crate::eval_state::EvalState::force), other `EvalState` methods, +/// or indirectly as a consequence of evaluating something else—all references +/// observe the evaluated result. This means +/// [`value_type_unforced`](crate::eval_state::EvalState::value_type_unforced) +/// can return `None` (thunk) initially but a specific type later, even without +/// directly operating on that `Value`. The state will not regress back to a +/// less determined state. pub struct Value { inner: NonNull, }