Skip to main content

Module forward

Module forward 

Source
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:

  1. takes the registry’s lock and holds it until the process ends, so no new child starts;
  2. sends the received signal, then SIGCONT, to every listed group, and to a listed child that moved to another group;
  3. waits up to FORWARD_GRACE until every listed child has exited;
  4. sends SIGKILL to every listed group;
  5. runs each clean-up that clean_up registered;
  6. 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_up to 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 calls start_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.