Panics: When a program stops

These messages never go to standard output, so a program's real output stays clean when it is piped into another program.

• Ctrl+C, a closed terminal and SIGTERM end the program the way cli.exit does: what it printed is flushed, and logs and traces are sent before it ends. A second Ctrl+C ends it at once.
• This holds for kavach run and for programs built with kavach build.

Finishing before a stop

A program with work it must not cut off (requests being answered, a file half written, a queue to empty) takes a hold with cli.on_stop(grace). While a hold is kept, the first stop signal doesn't end the program: hold.asked() turns true, and the program finishes what it is doing.

use std.cli
use std.time

fn main() uses Clock {
    const hold = cli.on_stop(grace: 30.seconds)
    while not hold.asked() {
        work_a_little()
    }
    save_progress()         // Docker's SIGTERM: this still runs
    hold.done()
}

• The program ends, with the signal's exit code, once every hold is let go of with hold.done(), when the longest grace has passed, or when main returns.
• A second signal ends it at once.
• A hold needs no capability. http.serve takes one of its own, so a server finishes the requests under way before the program ends.

Without a stop signal, hold.asked() stays false:

use std.cli

fn main() {
    const hold = cli.on_stop(grace: 30.seconds)
    let rounds = 0
    while not hold.asked() and rounds < 3 {
        rounds += 1
    }
    print("asked: {hold.asked()}, rounds: {rounds}")
    print("saving progress")
    hold.done()
}

asked: false, rounds: 3saving progress