Skip to main content

Module once

Module once 

Source
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§

KeptError
An error a cell keeps, with the charge for its heap.

Traits§

CellError
What a cell must know about an error before it keeps it.

Functions§

get_or_publish
The value in cell, computing it with compute first when there is none. compute runs 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 with compute first when there is none (as get_or_publish). An error the input decides is published with a charge on meter for 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. meter is 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§

ResultCell
A cell of a fallible value: the value, or an input-determined error with its charge.