Skip to main content

Crate kizz_threads

Crate kizz_threads 

Source
Expand description

The one place where kizz starts threads, and where it locks the state that threads share (“Kizz never panics”).

spawn starts a named thread, and spawn_scoped starts one in a std::thread::scope. Neither panics: where std::thread::spawn and std::thread::Scope::spawn panic when the system refuses a thread, these return a StartError. When the system cannot start a thread for the moment, which it reports as EAGAIN and Rust as io::ErrorKind::WouldBlock, they wait and try again, after each of the waits of WAITS in turn: 100, 200, 400, 800, 1,600 and 3,200 milliseconds, then 4 seconds four times, 22.3 seconds in all. Any other error, or a tenth retry that fails, is the error, which names the thread, the attempts, the time waited and the system’s error. The waits have no random part, and each start retries on its own, so a start never waits longer than that.

std::thread::Builder drops the work of a start that fails, so the helper keeps the work outside each attempt, and a thread that starts after retries runs it exactly once. The helper’s calls of std::thread::Builder sit in one private module, under the one allowance of production code for the bans of clippy.toml, which forbid every other way of starting a thread.

In builds with debug_assertions, which tests use and release builds lack, the module testing can make the next attempts to start threads fail on purpose, for one thread and the threads that it starts through the helper, or for every thread of the process. Those attempts go through the same retries, which then record each wait instead of sleeping, so tests check the waits exactly and finish at once. A release build has no such module and cannot fail a start on purpose.

lock locks a Mutex without Mutex::lock, which may panic when the calling thread already holds the lock. It tries the lock with Mutex::try_lock, which cannot panic, and while another holder keeps it, it yields and then sleeps between tries, for at most LOCK_PATIENCE; a lock that stays held that long, such as one that the calling thread holds itself, is a LockError that names what the lock guards. A lock that a panicking thread left behind is taken as it is, as Mutex::lock would return it with its poison.

overflow holds kizz’s handler of stack overflows. Once overflow::install has installed it, spawn and spawn_scoped set up each thread at the start of its work, with an alternate signal stack and the guard region of its stack, and undo that when the work ends; before then, they do nothing new.

Modules§

overflow
Kizz’s handler of stack overflows (“Kizz never panics”).
testing
Failures of thread starts that tests cause on purpose, only in builds with debug_assertions, which tests use and release builds lack.

Structs§

JoinHandle
The handle of a thread that spawn started.
LockError
A lock that stayed held for longer than kizz waits for it.
ScopedJoinHandle
The handle of a thread that spawn_scoped started.
StartError
A thread that could not be started.

Constants§

LOCK_PATIENCE
How long lock waits for a lock that another holder keeps before it gives up: far longer than kizz holds any lock, which is only for a few operations on the data that it guards.
WAITS
The waits before each retry of a start that the system refused for the moment: they double from 100 milliseconds up to 4 seconds, 22.3 seconds in all, so a start makes at most 11 attempts.

Functions§

lock
Lock mutex, which guards what, such as “the build’s warnings”, waiting at most LOCK_PATIENCE while another holder keeps it.
lock_within
Lock mutex, which guards what, waiting at most patience while another holder keeps it: lock with a patience of its own, for tests.
spawn
Start a thread named name, which is what, such as “the tracing thread”, to run work, retrying while the system cannot start it for the moment.
spawn_scoped
Start a thread named name in scope, which is what, such as “the thread that feeds stdin”, to run work, retrying while the system cannot start it for the moment.