Expand description
Stops every live child group when the tool itself receives SIGINT,
SIGTERM or SIGHUP, runs the tool’s clean-ups, and then takes the
signal’s default action. It exists on Unix with the forward feature.
install starts one thread for the life of the process. When a
signal arrives, the thread:
- takes the registry’s lock and holds it until the process ends, so no new child starts;
- sends the received signal, then SIGCONT, to every listed group, and to a listed child that moved to another group;
- waits up to
FORWARD_GRACEuntil every listed child has exited; - sends SIGKILL to every listed group;
- runs each clean-up that
clean_upregistered; - takes the signal’s default action, which ends the tool as the signal would have.
A run lists its child while it holds the registry’s lock around the
start, when the child leads a group of its own
(Scope::Group). The run unlists it under the
same lock before it reaps it, so the forwarder never signals a process
id that another process may have taken.
The forwarder must be the only handler that ends the tool on SIGINT,
SIGTERM or SIGHUP. A tool that keeps crumbkit-usage’s log beside the
forwarder starts it with start_under(forward::clean_up), so the log
starts no signal thread. The line is the first clean-up only when
start_under runs before anything else registers one. Plain
start beside install leaves two handlers that each end the tool,
and neither crate can detect that (ADR-0179).
A tool that hands the terminal to a child with crumbkit-child calls
handed_over just before the hand-over, so Ctrl-C ends only the child.
fn remove_lock_file() {}
crumbkit_process::forward::clean_up(remove_lock_file);
crumbkit_process::forward::install()?;Constants§
- FORWARD_
GRACE - How long the forwarder waits for the listed children to exit after it sends them the tool’s signal, before it sends SIGKILL.
Functions§
- clean_
up - Registers
clean_upto run when the forwarder has stopped the listed groups and before the tool ends. The clean-ups run in the order that they were registered, each function is kept once, and a clean-up that panics does not stop the others. A clean-up that never returns stops the later ones, so a tool that must write crumbkit-usage’s line callsstart_under(forward::clean_up)before it registers anything else. - handed_
over - Tells the forwarder that a child is about to take the terminal. From now until the tool ends, the forwarder drops SIGINT, as crumbkit-child ignores it on Unix (ADR-0042, ADR-0179), so Ctrl-C reaches only the child. SIGTERM and SIGHUP still reach the listed groups as before. The child that takes the terminal is not on the forwarder’s list, so a SIGTERM or SIGHUP sent to the tool during a hand-over ends the tool and leaves that child on the terminal.
- install
- Starts the thread that forwards SIGINT, SIGTERM and SIGHUP to every live child group. A second call does nothing and returns the result of the first.