Module signal_hook::pipe

Module with the self-pipe pattern.

One of the common patterns around signals is to have a pipe with both ends in the same program. Whenever there's a signal, the signal handler writes one byte of garbage data to the write end, unless the pipe's already full. The application then can handle the read end.

This has two advantages. First, the real signal action moves outside of the signal handler where there are a lot less restrictions. Second, it fits nicely in all kinds of asynchronous loops and has less chance of race conditions.

This module offers premade functions for the write end (and doesn't insist that it must be a pipe ‒ anything that can be written to is fine ‒ sockets too, therefore UnixStream::pair is a good candidate).

If you want to integrate with some asynchronous library, plugging streams from mio-uds or tokio-uds libraries should work.

If it looks too low-level for your needs, the iterator module contains some higher-lever interface that also uses a self-pipe pattern under the hood.

Correct order of handling

A care needs to be taken to avoid race conditions, especially when handling the same signal in a loop. Specifically, another signal might come when the action for the previous signal is being taken. The correct order is first to clear the content of the pipe (read some/all data from it) and then take the action. This way a spurious wakeup can happen (the pipe could wake up even when no signal came after the signal was taken, because ‒ it arrived between cleaning the pipe and taking the action). Note that some OS primitives (eg. select) suffer from spurious wakeups themselves (they can claim a FD is readable when it is not true) and blocking read might return prematurely (with eg. EINTR).

The reverse order of first taking the action and then clearing the pipe might lose signals, which is usually worse.

This is not a problem with blocking on reading from the pipe (because both the blocking and cleaning is the same action), but in case of asynchronous handling it matters.

If you want to combine setting some flags with a self-pipe pattern, the flag needs to be set first, then the pipe written. On the read end, first the pipe needs to be cleaned, then the flag and then the action taken. This is what the Signals structure does internally.

Write collating

While unlikely if handled correctly, it is possible the write end is full when a signal comes. In such case the signal handler simply does nothing. If the write end is full, the read end is readable and therefore will wake up. On the other hand, blocking in the signal handler would definitely be a bad idea.

However, this also means the number of bytes read from the end might be lower than the number of signals that arrived. This should not generally be a problem, since the OS already collates signals of the same kind together.

Examples

This example waits for at last one SIGUSR1 signal to come before continuing (and terminating). It sends the signal to itself, so it correctly terminates.

extern crate libc;
extern crate signal_hook;

use std::io::{Error, Read};
use std::os::unix::net::UnixStream;

fn main() -> Result<(), Error> {
    let (mut read, write) = UnixStream::pair()?;
    signal_hook::pipe::register(signal_hook::SIGUSR1, write)?;
    // This will write into the pipe write end through the signal handler
    unsafe { libc::raise(signal_hook::SIGUSR1) };
    let mut buff = [0];
    read.read_exact(&mut buff)?;
    println!("Happily terminating");
    Ok(())
}

Functions

register	Registers a write to a self-pipe whenever there's the signal.
register_raw	Registers a write to a self-pipe whenever there's the signal.