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§
- Join
Handle - The handle of a thread that
spawnstarted. - Lock
Error - A lock that stayed held for longer than kizz waits for it.
- Scoped
Join Handle - The handle of a thread that
spawn_scopedstarted. - Start
Error - A thread that could not be started.
Constants§
- LOCK_
PATIENCE - How long
lockwaits 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 guardswhat, such as “the build’s warnings”, waiting at mostLOCK_PATIENCEwhile another holder keeps it. - lock_
within - Lock
mutex, which guardswhat, waiting at mostpatiencewhile another holder keeps it:lockwith a patience of its own, for tests. - spawn
- Start a thread named
name, which iswhat, such as “the tracing thread”, to runwork, retrying while the system cannot start it for the moment. - spawn_
scoped - Start a thread named
nameinscope, which iswhat, such as “the thread that feeds stdin”, to runwork, retrying while the system cannot start it for the moment.