Skip to main content

Module waits

Module waits 

Source
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), so call_once names call_once_force too.
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::thread itself and its aliases (only available_parallelism is allowed), spin hints, condition variables, barriers, channels, a thread pool.

Functions§

cell_fills
Every file:line: token under src, src/once.rs itself excepted, where non-test code fills a cell other than through the once helper (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: token under src where non-test code names a FORBIDDEN token (the first on the line).