Skip to main content

Module overflow

Module overflow 

Source
Expand description

Kizz’s handler of stack overflows (“Kizz never panics”).

Kizz does not prevent a stack overflow, such as one in Starlark’s garbage collector when a task program nests values too deeply. It catches the overflow instead and stops in a controlled way, where Rust’s runtime would abort the process.

  • install sets up the calling thread, the main thread, and installs the handler for SIGSEGV and SIGBUS, with SA_SIGINFO and SA_ONSTACK, after it has kept the earlier action of each signal. It installs the handler for both signals or for neither, and its error names the call that failed.
  • Setting up a thread gives it an alternate signal stack of its own, of 64 KiB plus the kernel’s AT_MINSIGSTKSZ, above an inaccessible guard page, and records the guard region of its stack in a thread-local value of plain integers. Once the handler is installed, crate::spawn and crate::spawn_scoped set up each thread at the start of its work, and restore its earlier alternate stack and unmap kizz’s one when the work ends; the main thread keeps its own. A thread whose alternate stack or guard region cannot be set up runs without them, silently.
  • note_task and note_lock keep the location of the task whose program kizz evaluates and the path of the lock file that it holds in static buffers of atomic bytes, guarded by a sequence counter, until the Note is dropped.

The handler acts only on a signal that the kernel raised for a fault (si_code above 0), in the process that installed it, at an address in the guard region of the faulting thread. It then writes a fixed error to standard error, naming the noted task when there is one, deletes the noted lock file, and exits with the status that install was given. It makes only calls that are safe in a signal handler (signal-safety(7)): write, unlink, _exit, sigaction and getpid. It allocates nothing, takes no lock, starts nothing and never returns into the overflowed code.

Any other fault goes to the action that was there before: the handler restores it with sigaction, keeping errno, and returns, so the fault repeats under std’s handler, which reports its own overflow or restores the default action. A real crash is never swallowed.

In builds with debug_assertions, fault_outside_guards makes the calling thread fault outside every guard region, for the kizz binary’s end-to-end test.

Structs§

InstallError
Why install could not install the handler.
Note
A note of note_task or note_lock, kept until it is dropped.

Functions§

fault_outside_guards
Fault outside every guard region, by reading a page that is mapped without access, so that the end-to-end test sees the handler hand the fault on; only in builds with debug_assertions, which tests use and release builds lack. It returns only when the page cannot be mapped.
install
Install kizz’s handler of stack overflows for the process, which exits with status after an overflow, and set up the calling thread, which must be the main thread, first. The main thread keeps its alternate stack.
note_lock
Note path, the lock file that kizz holds, so that the handler deletes it, until the note is dropped. A path longer than 4,095 bytes, or one that holds a zero byte, is not noted; the next build then takes the file over.
note_task
Note text, the location of the task whose program kizz evaluates, such as kizz.md:12 (Deep), so that the handler names it, until the note is dropped. A text longer than 1,024 bytes is cut at a character boundary.