Expand description
Lazily computed values, published without holding anything while they are computed.
A lazy value in the core (a parsed bundle entry, a compiled tree, a
container, a registry slot) may take caller code to compute: a
crate::codec::BlockCodec, a crate::provider::TypeTreeProvider, the
crate::budget::MemoryBudget every charge books with. Computing it
inside OnceLock::get_or_init would run that code while the cell is
locked, so a callback that reaches the same cell deadlocks, and a binding
thread holding Python’s GIL while it waits on the cell deadlocks against
a computing thread whose Python callback needs the GIL (plan section
3.16). get_or_publish computes with nothing held and then publishes:
the first value published wins, and a value computed by a thread that
lost the race is dropped (its charges with it).
Fallible values go through get_or_publish_result, which publishes
a value and the errors the input decides, and never a transient one: a
budget or meter refusal depends on what else is held at that moment (two
threads computing the same value at once can cause it themselves), so
publishing it would fail every later ask of a shared dependency for the
handle’s life, however empty the pool later is. A transient error is
returned unpublished and the next ask computes again. A published error
is charged to the input’s meter for the heap it owns (CellError), so
a table of failing cells is paid for like any other, and every later ask
gets a clone that shares that heap (the core’s errors hold their strings
and nested errors in Arcs), so a caller that keeps many answers holds
no more (tests/files_memory.rs).
Work. A computation that ends in an error its cell does not keep runs
again on the next ask, so an input could make its readers repeat it
without end (one type whose compile alone needs more than the meter,
asked by every object of the type). When the input’s meter itself
refused it (CellError::is_meter_refusal), every byte the meter
granted to the computation on its own thread is therefore counted as the
open’s work (crate::limits::Limits::max_decode_work, shared with
block decodes), and once work has passed that allowance an ask that would
compute keeps a crate::LimitKind::DecodeWork refusal instead, which
is not transient. Nothing else counts (round 6): grants another thread
made on the same meter meanwhile are that thread’s work, and a refusal
by the budget, an I/O failure or a provider’s failure depends on what
else is held or on caller code, so counting it would let contention use
up a valid shared dependency’s allowance for the handle’s life. Those
repeat as often as the caller asks, which the engine bounds (plan 4.1).
A compute has no side effect but its charges: what follows from a value (registering a nested container’s entries) is done from the published value, after publishing, so a value that lost the race leaves nothing.
Owner: the scaffold (implemented). Every lazily computed value in the
core goes through it; no get_or_init runs anything but a move.
Structs§
- Kept
Error - An error a cell keeps, with the charge for its heap.
Traits§
- Cell
Error - What a cell must know about an error before it keeps it.
Functions§
- get_
or_ publish - The value in
cell, computing it withcomputefirst when there is none.computeruns with no lock held, so it may call caller code, and it may even re-enter this cell; when two threads compute at once, the first to publish wins and the other’s value is dropped. - get_
or_ publish_ result - The value in
cell, computing it withcomputefirst when there is none (asget_or_publish). An error the input decides is published with a charge onmeterfor its heap, and returned (cloned) to every later ask; a transient error (CellError::is_transient), or one whose charge the meter refuses, is returned unpublished, so the next ask computes again.meteris the meter of the open the computation charges: what it granted the computation, on this thread, counts as that open’s work when the computation ends in the meter’s own refusal, and once the work has passed its allowance an ask keeps a refusal instead of computing (module docs).
Type Aliases§
- Result
Cell - A cell of a fallible value: the value, or an input-determined error with its charge.