Struct Thunk 

pub struct Thunk(/* private fields */);

A lazy value with memoization and blackhole detection.

Implementations

impl Thunk

pub fn new_suspended(expr: Expr, env: Env) -> Self

Create a thunk that will evaluate expr in env when forced.

pub fn new_suspended_recursive(expr: Expr, env: Env) -> Self

Like [new_suspended] but marks the thunk as self-recursive. On force, inner re-entrance returns the partial value from the promise cell instead of erroring with InfiniteRecursion, matching cppnix’s let x = f x; in x semantics. Use this for let-bindings whose RHS textually references the bound name (see eval::is_self_recursive_binding).

pub fn new_inherit_select(source_thunk: Thunk, name: impl Into<SmolStr>) -> Self

Create a thunk that, when forced, forces the shared source_thunk and pulls out the attribute named name.

The caller creates ONE Thunk::new_suspended(source_expr, env) per inherit (source) clause and passes clones (Rc bump) to each inherited name. This way the source is evaluated at most once regardless of how many names are inherited.

pub fn new_with_ident( name: SmolStr, scope_cache: Rc<RefCell<Option<NixAttrs>>>, scope_value: Value, env: Env, ) -> Self

Create a WithIdent thunk — a deferred with-scope ident lookup. Stores a direct reference to the shared with-scope cache. When forced: O(1) hash lookup in the cache, no Env traversal.

pub fn new_native( f: impl FnOnce() -> Result<Value, EvalError> + 'static, ) -> Self

Create a thunk backed by a Rust closure. When forced, the closure is called exactly once and its result is memoized. This is used for lazy flake input evaluation.

pub fn new_evaluated(value: Value) -> Self

Create a thunk that is already evaluated (an optimization). Pre-populates the OnceCell cache so the fast path is immediately available.

pub fn is_evaluated(&self) -> bool

Check whether this thunk has already been forced. Uses the OnceCell cache for a fast, borrow-free check.

pub fn is_native(&self) -> bool

Check whether this thunk is a native (Rust closure) thunk.

Native thunks are used for lazy flake input evaluation and can be very expensive to force (e.g., evaluating all of nixpkgs). This lets callers skip them in eager conversion paths.

pub fn peek(&self) -> Option<&Concrete>

Peek at the cached value WITHOUT forcing. Returns Some(&Value) if the thunk has been evaluated, None otherwise. This is used by with-scope lookup to check if the fixpoint thunk has already been resolved (by another evaluation path) without entering the force state machine.

pub fn update_env(&self, new_env: &Env)

Replace the environment captured in a suspended thunk. For InheritSelect, delegates to the shared source thunk’s update_env (which updates the source’s captured env). No-op if the thunk is already evaluated or a blackhole.

pub fn force( &self, evaluator: &dyn Fn(&Expr, &Env) -> Result<Value, EvalError>, ) -> Result<Value, EvalError>

Force this thunk using the given evaluator function.

On first force: transitions Suspended -> Blackhole -> Evaluated. Re-entering a Blackhole signals infinite recursion. If the evaluated result is itself a thunk, it is forced transitively.

Uses stacker::maybe_grow to ensure sufficient stack space for deeply nested thunk chains (e.g., nixpkgs overlay fixpoints).

Trait Implementations

impl Clone for Thunk

fn clone(&self) -> Thunk

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Thunk

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.