Expand description
The source scans behind plan section 4.1’s rules that the core never waits and never starts a thread, and that it computes no lazy value inside its cell.
Waits. A batch engine runs core calls on its own pool threads, so a
core call that parks, sleeps, spins, waits on a condition or a channel,
or hands work to a thread of its own would let the pool starve itself, or
escape the engine’s bound on threads. waits lists every line outside
test code that names one of FORBIDDEN: a thread function by its path
or bare (as a grouped or aliased import calls it), any use of
std::thread but available_parallelism, an alias of it, a spin hint
(std::hint::spin_loop, the older spin_loop_hint), a condition
variable, a barrier, a channel or a thread pool. A call token (one that
ends in () matches with a turbofish and with spaces before its
parenthesis too (spawn::<F, T>(, sleep ().
Cells. A value computed inside OnceLock::get_or_init (or a
LazyLock, a Once) runs caller code with the cell locked, which a
callback that reaches the same cell, or a thread holding Python’s GIL,
deadlocks on (plan 3.16). cell_fills lists every line outside test
code and outside the crate’s own src/once.rs (that one file: a once.rs
elsewhere in the tree is scanned) that names a cell-filling method or
type, by any form of call, a turbofish’s included, or as a path, so
fills a cell any other way than through
once::get_or_publish or get_or_publish_result, whose tests pin that
only a move runs inside the cell. So every lazy value of the core, the
stubs’ included once they are written, goes through the tested helper.
What neither scan checks: locks. The scan cannot tell a lock held for
a lookup from one held across a call into caller code (a codec, a
provider, a resolver, a fetcher). That no core lock is held across caller
code is checked by tests that re-enter each public path that takes one:
the provider chain’s (provider::tests), and packages C’s and D’s for
the bundle and the Environment (plan 4.1, 7.4, 7.5).
Test code is an item, field, match arm or statement under
#[cfg(test)], found by bracket depth, not by line endings: an item
(fn, mod, impl, use, a macro such as thread_local!) ends at the
; or the closing } of its first block at its own depth; anything
else (a struct field, a struct literal’s field, a match arm, a statement)
also ends at a , at its own depth, and at the } or ) that closes
what encloses it. String and character literals and comments do not
count toward the depth; comments are never scanned.
Owner: the scaffold (implemented).
Constants§
- CELL_
FILLS - What fills a cell with caller code inside it, outside
once.rs: each named at the start of a word, whatever follows (a call, a turbofish, a path), socall_oncenamescall_once_forcetoo. - FORBIDDEN
- What the core never names outside tests: thread starts, sleeps, parks,
spins and scopes (by path, or bare as an import calls them),
std::threaditself and its aliases (onlyavailable_parallelismis allowed), spin hints, condition variables, barriers, channels, a thread pool.
Functions§
- cell_
fills - Every
file:line: tokenundersrc,src/once.rsitself excepted, where non-test code fills a cell other than through theoncehelper (CELL_FILLS). - live_
code - The source’s live code: every comment, every test item and every
string and character literal blanked to spaces (newlines kept, so line
numbers hold), for a scan that matches code forms and counts braces
(the core’s CR8 refusal scan,
counters_scan_tests.rs). - waits
- Every
file:line: tokenundersrcwhere non-test code names aFORBIDDENtoken (the first on the line).