pub struct Cancellation { /* private fields */ }Expand description
A shared handle that cancels a running request, or forwards signals to it.
Clones share the handle, so the engine keeps one clone and hands another to the tracer. When the flag is set, the tracer interrupts the request’s process tree, kills whatever remains of it after a grace period, and returns its result once the whole tree has exited. The result reports how the command ended: by a signal, or with an exit code that the command chose after it handled the interrupt.
The caller can also forward a Signal with Cancellation::forward, as
kizz execute forwards the SIGTERM and SIGHUP that kizz receives. A tracer
takes each forwarded signal with Cancellation::take_forwarded while the
request runs, and delivers it once: to the command’s first process while that
process lives, and afterwards to each live process of the tree. A signal that
is forwarded again before the tracer takes it is delivered once, as a pending
signal of the operating system is, and one forwarded while no request runs
waits for the next request that holds a clone. Once the request is cancelled,
the tracer forwards nothing more. Builds never forward a signal.
A signal sent to the whole process group of a command that keeps the terminal
(RunRequest::terminal) reaches the command directly, and once more when the
caller, which received it too, forwards it: neither the caller nor the tracer can
tell such a signal from one sent to the caller alone.
The handle uses only atomic operations, so the caller can forward a signal from anywhere, a signal handler included.
Implementations§
Source§impl Cancellation
impl Cancellation
Sourcepub fn is_cancelled(&self) -> bool
pub fn is_cancelled(&self) -> bool
Whether cancellation was requested.
Sourcepub fn forward(&self, signal: Signal)
pub fn forward(&self, signal: Signal)
Forward signal to the request that holds a clone of this handle, for its
tracer to deliver once, as the type’s documentation says.
Sourcepub fn take_forwarded(&self) -> Vec<Signal>
pub fn take_forwarded(&self) -> Vec<Signal>
Take every signal forwarded since the last call, in the order of
Signal::ALL, so each one is delivered once.