Signal Handling and Clean Shutdown

21 min read

A long-running process — a web server, a queue worker, a daemon — does not get to choose when it dies. The operating system, an orchestrator like Kubernetes, or a developer hitting Ctrl-C will send it a signal and expect it to wind down gracefully: stop accepting work, finish in-flight requests, flush logs and buffers, release locks, and exit. This page is about catching those signals in Rust and turning an abrupt kill into an orderly shutdown.

Quick Overview

A signal is an asynchronous notification the kernel delivers to a process — SIGINT (Ctrl-C), SIGTERM (the polite “please stop” an orchestrator sends), SIGHUP (terminal hang-up, often repurposed as “reload config”), and others. By default most of them just terminate your process immediately. To shut down cleanly you install a handler that flips a flag, and your main loop notices the flag and unwinds in an orderly way.

If you have written a Node service you have done this with process.on("SIGTERM", ...). Rust has no built-in process.on; instead you reach for one of two well-maintained crates: ctrlc for the simple “catch Ctrl-C / terminate signals and run a closure” case, or signal-hook for everything more demanding (specific signals, iterating over signals on a dedicated thread, double-Ctrl-C force-quit, async runtimes). The current stable toolchain is Rust 1.96.0 on the latest stable edition (2024), and cargo new selects it automatically; every Rust snippet below was compiled and run on stable.

Note: Signals are a Unix concept. On Windows the closest equivalents are console control events (Ctrl-C, Ctrl-Break) and there is no SIGTERM. The ctrlc crate papers over the difference for the Ctrl-C case; signal-hook and Tokio’s Unix signal API are Unix-only. This page focuses on Unix (Linux/macOS), which is where servers run. For related building blocks see atomic operations (the AtomicBool flag pattern), channels (waking a worker on shutdown), and process management (sending signals to child processes).

TypeScript/JavaScript Example

In Node, the process object is an EventEmitter and signals arrive as events. A production-grade shutdown handler typically: sets a “shutting down” flag so a second Ctrl-C can force-quit, stops the work source, drains in-flight work with a timeout, then calls process.exit.

1
// shutdown.mts — Node v22
2
let shuttingDown = false;
3
const timer = setInterval(() => {}, 1000); // stand-in for "the server is alive"
4

5
function shutdown(signal: NodeJS.Signals): void {
6
  // A SECOND signal while we are already draining: give up and force-quit.
7
  if (shuttingDown) {
8
    console.log(`\n${signal} again — force exit`);
9
    process.exit(1);
10
  }
11
  shuttingDown = true;
12
  console.log(`\n${signal} received: draining...`);
13
  clearInterval(timer); // stop accepting new work
14
  // Finish in-flight work, then exit. A real server would await its drain.
15
  setTimeout(() => {
16
    console.log("clean exit");
17
    process.exit(0);
18
  }, 50);
19
}
20

21
process.on("SIGINT", () => shutdown("SIGINT")); // Ctrl-C
22
process.on("SIGTERM", () => shutdown("SIGTERM")); // `kill`, Docker stop, k8s
23
console.log(`pid ${process.pid} running`);

Running it and sending SIGTERM (the same signal docker stop and Kubernetes send) prints:

1
pid 80723 running
2

3
SIGTERM received: draining...
4
clean exit

Key facts about the Node model:

The signal handler runs on the main thread between event-loop ticks — it is not preemptive. Your callback is ordinary JavaScript and can touch any state.
If you register no SIGTERM listener, Node uses the OS default and the process dies instantly with no chance to clean up.
The async drain (setTimeout / await) works because Node’s event loop is still running; once you call process.exit, pending callbacks are abandoned.

Rust Equivalent

Rust does not let you run arbitrary code in a real OS signal handler (signal handlers are wildly restricted — almost nothing is async-signal-safe). The idiomatic pattern is therefore: a tiny handler that only sets an AtomicBool, and a main loop that polls it. The ctrlc crate wraps this safely.

1
[dependencies]
2
ctrlc = "3"

1
use std::sync::atomic::{AtomicBool, Ordering};
2
use std::sync::Arc;
3
use std::thread;
4
use std::time::Duration;
5

6
fn main() {
7
    // Shared, thread-safe flag. The signal handler sets it; main reads it.
8
    let running = Arc::new(AtomicBool::new(true));
9
    let r = Arc::clone(&running);
10

11
    // `set_handler` installs a handler for Ctrl-C (and SIGTERM with the
12
    // default feature set on Unix). The closure runs on a dedicated thread.
13
    ctrlc::set_handler(move || {
14
        println!("\nreceived Ctrl-C, shutting down...");
15
        r.store(false, Ordering::SeqCst);
16
    })
17
    .expect("error setting Ctrl-C handler");
18

19
    println!("working... press Ctrl-C to stop");
20
    let mut tick = 0u64;
21
    while running.load(Ordering::SeqCst) {
22
        thread::sleep(Duration::from_millis(50));
23
        tick += 1;
24
        // (Demo only) stop on our own after a few ticks so the program ends.
25
        // In a real service this loop runs until a signal flips `running`.
26
        if tick >= 4 {
27
            running.store(false, Ordering::SeqCst);
28
        }
29
    }
30
    println!("clean exit after {tick} ticks");
31
}

Output (the demo stops itself; in a real run, pressing Ctrl-C ends it):

1
working... press Ctrl-C to stop
2
clean exit after 4 ticks

For real services you usually want more control — specific signals, a SIGHUP-means-reload distinction, or the double-signal force-quit. That is signal-hook’s job:

1
[dependencies]
2
signal-hook = "0.4"

1
use signal_hook::consts::TERM_SIGNALS; // SIGTERM, SIGQUIT, SIGINT
2
use signal_hook::flag;
3
use std::sync::atomic::{AtomicBool, Ordering};
4
use std::sync::Arc;
5
use std::thread;
6
use std::time::Duration;
7

8
fn main() -> Result<(), Box<dyn std::error::Error>> {
9
    let shutdown = Arc::new(AtomicBool::new(false));
10

11
    // `flag::register` wires "when this signal arrives, set this bool to true".
12
    // No closure, no async-signal-safety footguns — the crate does it right.
13
    for &sig in TERM_SIGNALS {
14
        flag::register(sig, Arc::clone(&shutdown))?;
15
    }
16

17
    println!(
18
        "server up (pid {}); send SIGINT/SIGTERM to stop",
19
        std::process::id()
20
    );
21

22
    while !shutdown.load(Ordering::Relaxed) {
23
        thread::sleep(Duration::from_millis(100));
24
    }
25

26
    println!("shutdown flag set — draining connections, flushing logs...");
27
    println!("bye");
28
    Ok(())
29
}

Running it and sending SIGTERM (via kill -TERM <pid>) prints:

1
server up (pid 51687); send SIGINT/SIGTERM to stop
2
shutdown flag set — draining connections, flushing logs...
3
bye

Detailed Explanation

Why you cannot just run code in a signal handler

When the kernel delivers a signal, it interrupts your program wherever it happens to be — possibly in the middle of malloc, holding a lock, halfway through a println!. Inside a real signal handler you may only call a short list of async-signal-safe functions; allocating memory, locking a mutex, or doing formatted I/O can deadlock or corrupt state. JavaScript hides this because Node delivers the “signal” to your callback between event-loop ticks, not in the real handler.

Both ctrlc and signal-hook solve this the same way: the actual OS handler does almost nothing — it writes to a static AtomicBool or to a self-pipe — and your normal code observes that later. The AtomicBool + polling loop is not a workaround you settle for; it is the correct architecture.

`ctrlc::set_handler` line by line

Arc::new(AtomicBool::new(true)) creates a flag on the heap that multiple threads can share. Arc is the thread-safe reference count (see reference counting); AtomicBool lets us mutate it without a Mutex.
let r = Arc::clone(&running) makes a second handle. We move r into the closure because the closure outlives main’s stack frame — it runs on a dedicated handler thread ctrlc spawns.
r.store(false, Ordering::SeqCst) is the entire handler body: flip the flag. (Ordering controls how this write becomes visible to other threads — see memory ordering. SeqCst is the safe default; Relaxed is also fine for a simple shutdown flag.)
The while running.load(...) loop is your real work. It checks the flag each iteration and exits the moment it goes false.

`signal-hook`’s `flag::register`

flag::register(sig, Arc<AtomicBool>) is signal-hook’s most ergonomic primitive: it associates a signal number with a bool and returns a SigId you could later use to unregister. Looping over TERM_SIGNALS — a constant slice of [SIGTERM, SIGQUIT, SIGINT] on Linux — registers all the “please terminate” signals at once, so any of them sets the same flag. There is no closure to get wrong and nothing unsafe in your code.

Where the analogy to Node breaks down

Aspect	Node.js	Rust (`ctrlc` / `signal-hook`)
Handler runs on	Main thread, between ticks	A dedicated handler thread (`ctrlc`) or you read a flag/stream
Handler body	Arbitrary JS — can touch all state	Effectively just “set a flag”; do real work in your own code
Default if unhandled	Process terminates	Process terminates
Async drain	`await` works (event loop alive)	You poll/select the flag; with Tokio you `select!` on a signal future
`SIGTERM` on Windows	Emulated/limited	Does not exist; only Ctrl-C/Ctrl-Break console events

Tip: Unlike Node, where forgetting to clearInterval/unref can keep the process alive, a Rust binary exits as soon as main returns. Your job is purely to break out of the loop cleanly; you do not have to tear down timers to let the process die.

Key Differences

Setting a flag vs. doing the work

The single most important mental shift: in Rust the signal handler does not perform the shutdown. It records that a shutdown was requested. The actual draining, flushing, and joining happens in your normal control flow once it observes the flag. This keeps everything you do during shutdown — allocating, logging, locking — out of the dangerous signal context.

`ctrlc` vs. `signal-hook` — which to reach for

Need	Use
”Catch Ctrl-C / terminate, run a closure”	`ctrlc`
Handle specific signals (`SIGHUP`, `SIGUSR1`, …)	`signal-hook`
Distinguish reload (`SIGHUP`) from shutdown	`signal-hook` (iterator)
Double-Ctrl-C force-quit	`signal-hook` (`register_conditional_shutdown`)
React on a dedicated thread, by name	`signal-hook` (`iterator::Signals`)
Inside Tokio / async	`tokio::signal` (built into Tokio)

ctrlc is intentionally minimal; signal-hook is the toolbox. They can even coexist, but pick one owner per signal.

Signals you will actually see in production

SIGINT (2) — interactive Ctrl-C in a terminal.
SIGTERM (15) — the polite “stop now”; what kill <pid>, docker stop, and Kubernetes send first. Honor it.
SIGKILL (9) — uncatchable. You cannot handle it; the kernel destroys you. This is why orchestrators give you a grace period after SIGTERM before escalating to SIGKILL.
SIGHUP (1) — historically “terminal disconnected”; conventionally repurposed by daemons to mean “reload configuration without restarting.”
SIGQUIT (3) — like SIGINT but conventionally produces a core dump; Ctrl-\ in a terminal.

Warning: You can never catch or ignore SIGKILL (9) or SIGSTOP (17/19). If your process must survive a kill -9, the answer is external supervision (systemd, an orchestrator) plus crash-safe persistence — not a signal handler.

Common Pitfalls

Pitfall 1: Doing heavy work inside the handler closure

It is tempting to write the whole shutdown — close the database, flush files, log a summary — directly inside ctrlc::set_handler(|| { ... }). With ctrlc the closure runs on a normal thread so it can allocate, but you still create races: the handler thread now mutates shared state concurrently with your main thread with no coordination. Keep the handler to “set the flag” and do the work in main, where you already own that state.

Pitfall 2: Registering two handlers for the same signal

ctrlc::set_handler may be called only once per process. A second call returns an error rather than silently replacing the first:

1
fn main() {
2
    ctrlc::set_handler(|| {}).expect("first handler ok");
3
    // Registering a SECOND handler returns Err(Error::MultipleHandlers).
4
    match ctrlc::set_handler(|| {}) {
5
        Ok(()) => println!("second handler installed (unexpected)"),
6
        Err(e) => println!("second set_handler failed: {e}"),
7
    }
8
}

Real runtime output:

1
second set_handler failed: Ctrl-C error: Ctrl-C signal handler already registered

The fix is architectural: install the handler exactly once at startup and share the resulting flag (or a channel) with everything that needs to know about shutdown.

Pitfall 3: A blocking call that never re-checks the flag

If your main loop is parked inside a blocking call — TcpListener::accept(), a blocking recv(), a long thread::sleep — flipping the flag does nothing until that call returns. The flag is set, but you are not looking at it. Solutions: use a non-blocking listener and poll (shown in the Real-World Example), set a read timeout, or wake the blocked thread with a channel the handler sends to.

Pitfall 4: Forgetting `move` and hitting a borrow/lifetime error

The handler closure outlives main’s stack frame, so it must own what it captures. If you write ctrlc::set_handler(|| { r.store(...) }) without move while r is a local, the compiler rejects it because the closure would borrow a value that does not live long enough. Add move and clone the Arc first (let r = Arc::clone(&running);) so both the handler and main keep a live handle. See closures and ownership rules for the underlying mechanics.

Pitfall 5: Expecting `SIGTERM` on Windows

signal-hook and tokio::signal::unix are Unix-only; SIGTERM has no Windows equivalent. If you ship cross-platform, gate Unix-specific signal code behind #[cfg(unix)] and rely on ctrlc (which handles Ctrl-C on both) for the portable path.

Best Practices

Handler sets a flag; main does the work. This is the whole discipline. Never drain or flush from inside the OS handler context.
Catch the full terminate family, not just Ctrl-C. Use signal-hook’s TERM_SIGNALS so kill / docker stop (which send SIGTERM) are honored, not only interactive SIGINT.
Bound your drain with a timeout. Orchestrators escalate SIGTERM to an uncatchable SIGKILL after a grace period (Kubernetes defaults to 30 seconds). If your clean shutdown can hang, cap it so you exit cleanly before you are killed.
Make the second signal a force-quit. A user who hits Ctrl-C twice wants out now. signal-hook’s register_conditional_shutdown forces an immediate process exit on the second signal so the process dies right away (shown below).
In async code, use the runtime’s signal support. Inside Tokio, tokio::signal::unix::signal gives you a future you can select! on — do not block a Tokio worker on a polling loop.
Log that you received a signal and when you finish. Shutdown is exactly when observability matters; a “received SIGTERM, draining, done” trail turns a mysterious restart into a readable one.

The production “graceful, then force-quit” pattern

This combines two signal-hook registrations per signal. register_conditional_shutdown says “if the flag is already true when this signal fires, immediately exit the process with the given status code (here 1)”; the plain register sets the flag. So the first signal requests a graceful shutdown and the second one force-exits the process. The 1 is the exit code used for the force-quit.

1
use signal_hook::consts::TERM_SIGNALS;
2
use signal_hook::flag;
3
use std::sync::atomic::{AtomicBool, Ordering};
4
use std::sync::Arc;
5
use std::thread;
6
use std::time::Duration;
7

8
fn main() -> Result<(), Box<dyn std::error::Error>> {
9
    let term = Arc::new(AtomicBool::new(false));
10

11
    for &sig in TERM_SIGNALS {
12
        // If `term` is ALREADY true when this signal fires, exit immediately
13
        // with status 1 (no graceful path) — so a 2nd Ctrl-C force-quits.
14
        flag::register_conditional_shutdown(sig, 1, Arc::clone(&term))?;
15
        // First signal: set our flag so the main loop shuts down gracefully.
16
        flag::register(sig, Arc::clone(&term))?;
17
    }
18

19
    println!(
20
        "running (pid {}). 1st signal = graceful, 2nd = force-quit",
21
        std::process::id()
22
    );
23

24
    let mut work_left = 30;
25
    while !term.load(Ordering::Relaxed) {
26
        thread::sleep(Duration::from_millis(100));
27
        work_left -= 1;
28
        if work_left == 0 {
29
            break;
30
        }
31
    }
32

33
    if term.load(Ordering::Relaxed) {
34
        println!("graceful shutdown requested; finishing current job...");
35
        thread::sleep(Duration::from_millis(150)); // simulate draining
36
        println!("done");
37
    } else {
38
        println!("work completed normally");
39
    }
40
    Ok(())
41
}

Sending a single SIGINT lets it drain and print done:

1
running (pid 58542). 1st signal = graceful, 2nd = force-quit
2
graceful shutdown requested; finishing current job...
3
done

Sending a second SIGINT while it is draining cuts the drain short — it never prints done and the process exits immediately with a failure status:

1
running (pid 58841). 1st signal = graceful, 2nd = force-quit
2
graceful shutdown requested; finishing current job...

Note: The order of the two registrations matters. Register the conditional-shutdown first so that on the second signal it runs and force-exits the process; the plain register keeps setting the flag for the graceful path on the first signal.

Reacting to signals by name on a dedicated thread

When you need to distinguish signals — SIGHUP reloads config, terminate signals shut down — signal-hook’s iterator::Signals turns signals into an ordinary iterator you drain on a background thread. low_level::signal_name gives you a printable name.

1
use signal_hook::consts::{SIGHUP, SIGINT, SIGQUIT, SIGTERM};
2
use signal_hook::iterator::Signals;
3
use signal_hook::low_level;
4
use std::error::Error;
5

6
fn main() -> Result<(), Box<dyn Error>> {
7
    let mut signals = Signals::new([SIGINT, SIGTERM, SIGHUP, SIGQUIT])?;
8
    let handle = signals.handle(); // lets us stop the iterator later
9

10
    // A background thread owns the signal stream and reacts to each signal.
11
    let worker = std::thread::spawn(move || {
12
        for signal in &mut signals {
13
            let name = low_level::signal_name(signal).unwrap_or("UNKNOWN");
14
            match signal {
15
                SIGHUP => println!("got {name}: reloading config (not shutting down)"),
16
                SIGINT | SIGTERM | SIGQUIT => {
17
                    println!("got {name}: initiating clean shutdown");
18
                    break;
19
                }
20
                _ => unreachable!(),
21
            }
22
        }
23
        println!("signal thread done");
24
    });
25

26
    // Simulate a config reload, then a termination request.
27
    low_level::raise(SIGHUP)?;
28
    std::thread::sleep(std::time::Duration::from_millis(100));
29
    low_level::raise(SIGTERM)?;
30

31
    worker.join().unwrap();
32
    handle.close(); // unblock the iterator if it were still looping
33
    println!("main exiting cleanly");
34
    Ok(())
35
}

Output:

1
got SIGHUP: reloading config (not shutting down)
2
got SIGTERM: initiating clean shutdown
3
signal thread done
4
main exiting cleanly

Async shutdown with Tokio

If your service is async, do not spawn a blocking poll loop — use Tokio’s own signal futures and select! so a signal cancels your server alongside everything else.

1
[dependencies]
2
tokio = { version = "1", features = ["full"] }

1
use tokio::signal::unix::{signal, SignalKind};
2
use tokio::time::{sleep, Duration};
3

4
#[tokio::main]
5
async fn main() -> Result<(), Box<dyn std::error::Error>> {
6
    let mut sigint = signal(SignalKind::interrupt())?;
7
    let mut sigterm = signal(SignalKind::terminate())?;
8

9
    // A long-running task we want to cancel cleanly on shutdown.
10
    let server = tokio::spawn(async {
11
        loop {
12
            sleep(Duration::from_millis(50)).await; // pretend: serve requests
13
        }
14
    });
15

16
    println!("server running (pid {})", std::process::id());
17

18
    // Wait for whichever termination signal arrives first.
19
    tokio::select! {
20
        _ = sigint.recv()  => println!("\nSIGINT received"),
21
        _ = sigterm.recv() => println!("\nSIGTERM received"),
22
    }
23

24
    println!("shutting down: stopping background tasks...");
25
    server.abort();
26
    sleep(Duration::from_millis(100)).await; // drain in-flight work
27
    println!("graceful shutdown complete");
28
    Ok(())
29
}

Sending SIGTERM produces:

1
server running (pid 72128)
2

3
SIGTERM received
4
shutting down: stopping background tasks...
5
graceful shutdown complete

Note: Rust futures are lazy — signal(...) only produces values once it is polled by a runtime, the opposite of an eager JavaScript Promise. That is why the signal future lives inside select! under #[tokio::main] rather than firing on its own. For more on this model see Section 11: async/concurrency.

Real-World Example

A TCP echo server that shuts down gracefully on SIGINT/SIGTERM. The catch with std’s TcpListener is that accept() blocks forever, so a flag alone would never be checked. The realistic std-only fix is a non-blocking listener that wakes every 50 ms to re-check the shutdown flag — and when shutdown is requested, it stops accepting new connections and exits cleanly.

1
[dependencies]
2
signal-hook = "0.4"

1
use signal_hook::consts::TERM_SIGNALS;
2
use signal_hook::flag;
3
use std::io::{Read, Write};
4
use std::net::{TcpListener, TcpStream};
5
use std::sync::atomic::{AtomicBool, Ordering};
6
use std::sync::Arc;
7
use std::time::Duration;
8

9
fn handle_client(mut stream: TcpStream) -> std::io::Result<()> {
10
    let mut buf = [0u8; 1024];
11
    let n = stream.read(&mut buf)?;
12
    stream.write_all(&buf[..n])?; // echo it back
13
    Ok(())
14
}
15

16
fn main() -> std::io::Result<()> {
17
    let shutdown = Arc::new(AtomicBool::new(false));
18
    for &sig in TERM_SIGNALS {
19
        flag::register(sig, Arc::clone(&shutdown))
20
            .expect("failed to register signal handler");
21
    }
22

23
    let listener = TcpListener::bind("127.0.0.1:0")?; // port 0 = OS picks one
24
    let addr = listener.local_addr()?;
25
    // Don't block forever in accept(); wake periodically to check the flag.
26
    listener.set_nonblocking(true)?;
27
    println!("echo server listening on {addr}");
28

29
    let mut handled = 0u32;
30
    while !shutdown.load(Ordering::Relaxed) {
31
        match listener.accept() {
32
            Ok((stream, _peer)) => {
33
                // Serve this connection in blocking mode (toy: one at a time).
34
                stream.set_nonblocking(false).ok();
35
                if handle_client(stream).is_ok() {
36
                    handled += 1;
37
                }
38
            }
39
            // No pending connection right now: nap, then re-check the flag.
40
            Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock => {
41
                std::thread::sleep(Duration::from_millis(50));
42
            }
43
            Err(e) => return Err(e),
44
        }
45
    }
46

47
    println!("shutdown signal received; served {handled} request(s). Closing listener.");
48
    Ok(())
49
}

Connecting two clients (each sends a line, gets it echoed) and then sending SIGTERM produces this server output:

1
echo server listening on 127.0.0.1:51002
2
shutdown signal received; served 2 request(s). Closing listener.

For a production server you would offload handle_client to a thread pool or run the whole thing on Tokio and track in-flight connections so the drain waits for them. The signal-handling skeleton — register a flag, poll it in the accept loop, report a clean exit — stays the same. For the lower-level networking details see low-level networking.

Exercises

Exercise 1 — Graceful counter

Difficulty: Beginner

Objective: Use ctrlc to turn an abrupt Ctrl-C into a clean exit that reports how much work it finished.

Instructions: Write a program that increments a counter in a loop (sleeping briefly each iteration). Install a ctrlc handler that flips a shared AtomicBool. When the flag goes false, break out and print Processed N items before shutdown. Goodbye!. (For a self-contained demo you may stop after a few iterations; in a real run, Ctrl-C ends it.)

Solution

1
use std::sync::atomic::{AtomicBool, Ordering};
2
use std::sync::Arc;
3
use std::thread;
4
use std::time::Duration;
5

6
fn main() {
7
    let running = Arc::new(AtomicBool::new(true));
8
    let r = Arc::clone(&running);
9
    ctrlc::set_handler(move || r.store(false, Ordering::SeqCst))
10
        .expect("error setting handler");
11

12
    let mut processed = 0u64;
13
    while running.load(Ordering::SeqCst) {
14
        thread::sleep(Duration::from_millis(20));
15
        processed += 1;
16
        if processed >= 3 {
17
            running.store(false, Ordering::SeqCst); // demo stop
18
        }
19
    }
20
    println!("Processed {processed} items before shutdown. Goodbye!");
21
}

Output:

1
Processed 3 items before shutdown. Goodbye!

Exercise 2 — Reload vs. shutdown

Difficulty: Intermediate

Objective: Distinguish SIGHUP (reload) from terminate signals using signal-hook’s iterator.

Instructions: Register the terminate signals plus SIGHUP. On a background thread, iterate the signals: count each SIGHUP as a config reload and print reload #N; on any terminate signal, print how many reloads happened and break. Drive it by raise-ing two SIGHUPs and then a SIGTERM.

Solution

1
use signal_hook::consts::{SIGHUP, SIGTERM, TERM_SIGNALS};
2
use signal_hook::iterator::Signals;
3
use signal_hook::low_level;
4
use std::error::Error;
5

6
fn main() -> Result<(), Box<dyn Error>> {
7
    let mut sigs: Vec<i32> = TERM_SIGNALS.to_vec();
8
    sigs.push(SIGHUP);
9
    let mut signals = Signals::new(&sigs)?;
10

11
    let t = std::thread::spawn(move || {
12
        let mut reloads = 0u32;
13
        for signal in &mut signals {
14
            if signal == SIGHUP {
15
                reloads += 1;
16
                println!("reload #{reloads}");
17
            } else {
18
                println!("terminating after {reloads} reload(s)");
19
                break;
20
            }
21
        }
22
    });
23

24
    low_level::raise(SIGHUP)?;
25
    std::thread::sleep(std::time::Duration::from_millis(50));
26
    low_level::raise(SIGHUP)?;
27
    std::thread::sleep(std::time::Duration::from_millis(50));
28
    low_level::raise(SIGTERM)?;
29

30
    t.join().unwrap();
31
    Ok(())
32
}

Output:

1
reload #1
2
reload #2
3
terminating after 2 reload(s)

Exercise 3 — Channel-driven shutdown

Difficulty: Intermediate / Advanced

Objective: Combine ctrlc with an mpsc channel so a blocked main loop wakes the instant a signal arrives, instead of polling a flag.

Instructions: Create a channel::<()>(). In the ctrlc handler, send(()). In the main loop, use rx.recv_timeout(...): on Ok(()) (or a Disconnected error) print a shutdown line and break; on Timeout, do one unit of work. This is strictly better than spin-polling because recv_timeout blocks until either a signal arrives or the timeout elapses.

Solution

1
use std::sync::mpsc::{channel, RecvTimeoutError};
2
use std::time::Duration;
3

4
fn main() {
5
    let (tx, rx) = channel::<()>();
6
    ctrlc::set_handler(move || {
7
        let _ = tx.send(()); // ignore error if the receiver is already gone
8
    })
9
    .expect("error setting handler");
10

11
    let mut iterations = 0u64;
12
    loop {
13
        match rx.recv_timeout(Duration::from_millis(20)) {
14
            // A signal was delivered (or the sender was dropped) -> shut down.
15
            Ok(()) | Err(RecvTimeoutError::Disconnected) => {
16
                println!("shutdown signal -> stopping after {iterations} iterations");
17
                break;
18
            }
19
            // No signal yet: do a unit of work and loop.
20
            Err(RecvTimeoutError::Timeout) => {
21
                iterations += 1;
22
                if iterations >= 3 {
23
                    println!("work complete after {iterations} iterations");
24
                    break;
25
                }
26
            }
27
        }
28
    }
29
}

Output (the demo finishes its work before any signal arrives):

1
work complete after 3 iterations

In a real run, pressing Ctrl-C during the loop makes recv_timeout return Ok(()) immediately and prints the shutdown signal -> stopping after N iterations branch.

Signal Handling and Clean Shutdown

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Why you cannot just run code in a signal handler

ctrlc::set_handler line by line

signal-hook’s flag::register

Where the analogy to Node breaks down

Key Differences

Setting a flag vs. doing the work

ctrlc vs. signal-hook — which to reach for

Signals you will actually see in production

Common Pitfalls

Pitfall 1: Doing heavy work inside the handler closure

Pitfall 2: Registering two handlers for the same signal

Pitfall 3: A blocking call that never re-checks the flag

Pitfall 4: Forgetting move and hitting a borrow/lifetime error

Pitfall 5: Expecting SIGTERM on Windows

Best Practices

The production “graceful, then force-quit” pattern

Reacting to signals by name on a dedicated thread

Async shutdown with Tokio

Real-World Example

Further Reading

Exercises

Exercise 1 — Graceful counter

Exercise 2 — Reload vs. shutdown

Exercise 3 — Channel-driven shutdown

`ctrlc::set_handler` line by line

`signal-hook`’s `flag::register`

`ctrlc` vs. `signal-hook` — which to reach for

Pitfall 4: Forgetting `move` and hitting a borrow/lifetime error

Pitfall 5: Expecting `SIGTERM` on Windows