1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
/*!
This crate provides a simplistic interface to subscribe to operating system
signals through a channel API. Use is extremely simple:

```no_run
use chan_signal::Signal;

let signal = chan_signal::notify(&[Signal::INT, Signal::TERM]);

// Blocks until this process is sent an INT or TERM signal.
// Since the channel is never closed, we can unwrap the received value.
signal.recv().unwrap();
```


# Example

When combined with `chan_select!` from the `chan` crate, one can easily
integrate signals with the rest of your program. For example, consider a
main function that waits for either normal completion of work (which is done
in a separate thread) or for a signal to be delivered:

```no_run
#[macro_use]
extern crate chan;
extern crate chan_signal;

use chan_signal::Signal;

fn main() {
    // Signal gets a value when the OS sent a INT or TERM signal.
    let signal = chan_signal::notify(&[Signal::INT, Signal::TERM]);
    // When our work is complete, send a sentinel value on `sdone`.
    let (sdone, rdone) = chan::sync(0);
    // Run work.
    ::std::thread::spawn(move || run(sdone));

    // Wait for a signal or for work to be done.
    chan_select! {
        signal.recv() -> signal => {
            println!("received signal: {:?}", signal)
        },
        rdone.recv() => {
            println!("Program completed normally.");
        }
    }
}

fn run(_sdone: chan::Sender<()>) {
    // Do some work.
    ::std::thread::sleep_ms(1000);
    // Quit normally.
    // Note that we don't need to send any values. We just let the
    // sending channel drop, which closes the channel, which causes
    // the receiver to synchronize immediately and always.
}
```

You can see this example in action by running `cargo run --example select`
in the root directory of this crate's
[repository](https://github.com/BurntSushi/chan-signal).

# Platform support (no Windows support)

This should work on Unix platforms supported by Rust itself.

There is no Windows support at all. I welcome others to either help me add it
or help educate me so that I may one day add it.


# How it works

Overview: uses the "spawn a thread and block on `sigwait`" approach. In
particular, it avoids standard asynchronous signal handling because it is
very difficult to do anything non-trivial inside a signal handler.

After the first call to `notify` (or `notify_on`), all signals defined in the
`Signal` enum are set to *blocked*. This is necessary for synchronous signal
handling using `sigwait`.

After the signals are blocked, a new thread is spawned and immediately blocks
on a call to `sigwait`. It is only unblocked when one of the signals in
the `Signal` enum are sent to the process. Once it's unblocked, it sends the
signal on all subscribed channels via a non-blocking send. Once all channels
have been visited, the thread blocks on `sigwait` again.

This approach has some restrictions. Namely, your program must comply with the
following:

* Any and all threads spawned in your program **must** come after the first
  call to `notify` (or `notify_on`). This is so all spawned threads inherit
  the blocked status of signals. If a thread starts before `notify` is called,
  it will not have the correct signal mask. When a signal is delivered, the
  result is indeterminate.
* No other threads may call `sigwait`. When a signal is delivered, only one
  `sigwait` is indeterminately unblocked.


# Future work

This crate exposes the simplest API I could think of. As a result, a few
additions may be warranted:

* Expand the set of signals. (Requires figuring out platform differences.)
* Allow channel unsubscription.
* Allow callers to reset the signal mask? (Seems hard.)
* Support Windows.
*/
#![deny(missing_docs)]

extern crate bit_set;
#[macro_use] extern crate chan;
#[macro_use] extern crate lazy_static;
extern crate libc;

use std::collections::HashMap;
use std::io;
use std::mem;
use std::ptr;
use std::sync::Mutex;
use std::thread;

use bit_set::BitSet;
use chan::Sender;
use libc::consts::os::posix88::{
    SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGABRT, SIGFPE, SIGKILL,
    SIGSEGV, SIGPIPE, SIGALRM, SIGTERM,
};
use libc::funcs::posix88::signal::kill;
use libc::funcs::posix88::unistd::getpid;

lazy_static! {
    static ref HANDLERS: Mutex<HashMap<Sender<Signal>, BitSet>> = {
        init();
        Mutex::new(HashMap::new())
    };
}

/// Create a new channel subscribed to the given signals.
///
/// The channel returned is never closed.
///
/// This is a convenience function for subscribing to multiple signals at once.
/// See the documentation of `notify_on` for details.
///
/// The channel returned has a small buffer to prevent signals from being
/// dropped.
///
/// **THIS MUST BE CALLED BEFORE ANY OTHER THREADS ARE SPAWNED IN YOUR
/// PROCESS.**
///
/// # Example
///
/// ```no_run
/// use chan_signal::Signal;
///
/// let signal = chan_signal::notify(&[Signal::INT, Signal::TERM]);
///
/// // Blocks until this process is sent an INT or TERM signal.
/// // Since the channel is never closed, we can unwrap the received value.
/// signal.recv().unwrap();
/// ```
pub fn notify(signals: &[Signal]) -> chan::Receiver<Signal> {
    let (s, r) = chan::sync(100);
    for &sig in signals {
        notify_on(&s, sig);
    }
    // dropping `s` is OK because `notify_on` acquires one.
    r
}

/// Subscribe to a signal on a channel.
///
/// When `signal` is delivered to this process, it will be sent on the channel
/// given.
///
/// Note that a signal is sent using a non-blocking send. Namely, if the
/// channel's buffer is full (or it has no buffer) and it isn't ready to
/// rendezvous, then the signal will be dropped.
///
/// There is currently no way to unsubscribe. Moreover, the channel given
/// here will be alive for the lifetime of the process. Therefore, the channel
/// will never be closed.
///
/// **THIS MUST BE CALLED BEFORE ANY OTHER THREADS ARE SPAWNED IN YOUR
/// PROCESS.**
pub fn notify_on(chan: &Sender<Signal>, signal: Signal) {
    let mut subs = HANDLERS.lock().unwrap();
    if subs.contains_key(chan) {
        subs.get_mut(chan).unwrap().insert(signal.as_sig() as usize);
    } else {
        let mut sigs = BitSet::new();
        sigs.insert(signal.as_sig() as usize);
        subs.insert((*chan).clone(), sigs);
    }
}

fn init() {
    SigSet::subscribable().thread_block_signals().unwrap();
    thread::spawn(move || {
        let mut listen = SigSet::subscribable();
        loop {
            let sig = listen.wait().unwrap();
            let subs = HANDLERS.lock().unwrap();
            for (s, sigs) in subs.iter() {
                if !sigs.contains(&(sig as usize)) {
                    continue;
                }
                chan_select! {
                    default => {},
                    s.send(Signal::new(sig)) => {},
                }
            }
        }
    });
}

/// Kill the current process. (Only used in tests.)
#[doc(hidden)]
pub fn kill_this(sig: Signal) {
    unsafe { kill(getpid(), sig.as_sig()); }
}

type Sig = libc::c_int;

/// The set of subscribable signals.
///
/// After the first call to `notify_on` (or `notify`), precisely this set of
/// signals are set to blocked status.
#[allow(missing_docs)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Signal {
    HUP,
    INT,
    QUIT,
    ILL,
    ABRT,
    FPE,
    KILL,
    SEGV,
    PIPE,
    ALRM,
    TERM,
    #[doc(hidden)]
    __NonExhaustiveMatch,
}

impl Signal {
    fn new(sig: Sig) -> Signal {
        match sig {
            SIGHUP => Signal::HUP,
            SIGINT => Signal::INT,
            SIGQUIT => Signal::QUIT,
            SIGILL => Signal::ILL,
            SIGABRT => Signal::ABRT,
            SIGFPE => Signal::FPE,
            SIGKILL => Signal::KILL,
            SIGSEGV => Signal::SEGV,
            SIGPIPE => Signal::PIPE,
            SIGALRM => Signal::ALRM,
            SIGTERM => Signal::TERM,
            sig => panic!("unsupported signal number: {}", sig),
        }
    }

    fn as_sig(self) -> Sig {
        match self {
            Signal::HUP => SIGHUP,
            Signal::INT => SIGINT,
            Signal::QUIT => SIGQUIT,
            Signal::ILL => SIGILL,
            Signal::ABRT => SIGABRT,
            Signal::FPE => SIGFPE,
            Signal::KILL => SIGKILL,
            Signal::SEGV => SIGSEGV,
            Signal::PIPE => SIGPIPE,
            Signal::ALRM => SIGALRM,
            Signal::TERM => SIGTERM,
            Signal::__NonExhaustiveMatch => unreachable!(),
        }
    }
}

/// Safe wrapper around sigset_t.
struct SigSet(sigset_t);

impl SigSet {
    fn empty() -> SigSet {
        let mut set = unsafe { mem::uninitialized() };
        unsafe { sigemptyset(&mut set) };
        SigSet(set)
    }

    /// Creates a new signal set with precisely the signals we're limited
    /// to subscribing to.
    fn subscribable() -> SigSet {
        let mut set = SigSet::empty();
        set.add(SIGHUP).unwrap();
        set.add(SIGINT).unwrap();
        set.add(SIGQUIT).unwrap();
        set.add(SIGILL).unwrap();
        set.add(SIGABRT).unwrap();
        set.add(SIGFPE).unwrap();
        set.add(SIGKILL).unwrap();
        set.add(SIGSEGV).unwrap();
        set.add(SIGPIPE).unwrap();
        set.add(SIGALRM).unwrap();
        set.add(SIGTERM).unwrap();
        set
    }

    fn add(&mut self, sig: Sig) -> io::Result<()> {
        unsafe { ok_errno((), sigaddset(&mut self.0, sig)) }
    }

    fn wait(&mut self) -> io::Result<Sig> {
        let mut sig: Sig = 0;
        let errno = unsafe { sigwait(&mut self.0, &mut sig) };
        ok_errno(sig, errno)
    }

    fn thread_block_signals(&self) -> io::Result<()> {
        let ecode = unsafe {
            pthread_sigmask(SIG_SETMASK, &self.0, ptr::null_mut())
        };
        ok_errno((), ecode)
    }
}

fn ok_errno<T>(ok: T, ecode: libc::c_int) -> io::Result<T> {
    if ecode != 0 { Err(io::Error::from_raw_os_error(ecode)) } else { Ok(ok) }
}

extern {
    fn sigwait(set: *mut sigset_t, sig: *mut Sig) -> Sig;
    fn sigaddset(set: *mut sigset_t, sig: Sig) -> libc::c_int;
    fn sigemptyset(set: *mut sigset_t) -> libc::c_int;
    fn pthread_sigmask(
        how: libc::c_int,
        set: *const sigset_t,
        oldset: *mut sigset_t,
    ) -> libc::c_int;
}

// Most of this was lifted out of rust-lang:rust/src/libstd/sys/unix/c.rs.

#[cfg(all(any(target_os = "linux", target_os = "android"),
          any(target_arch = "x86",
              target_arch = "x86_64",
              target_arch = "powerpc",
              target_arch = "arm",
              target_arch = "aarch64")))]
const SIG_SETMASK: libc::c_int = 2;

#[cfg(all(any(target_os = "linux", target_os = "android"),
          any(target_arch = "mips", target_arch = "mipsel")))]
const SIG_SETMASK: libc::c_int = 3;

#[cfg(any(target_os = "macos",
          target_os = "ios",
          target_os = "freebsd",
          target_os = "dragonfly",
          target_os = "bitrig",
          target_os = "netbsd",
          target_os = "openbsd"))]
const SIG_SETMASK: libc::c_int = 3;

#[cfg(all(target_os = "linux", target_pointer_width = "32"))]
#[repr(C)]
struct sigset_t {
    __val: [libc::c_ulong; 32],
}

#[cfg(all(target_os = "linux", target_pointer_width = "64"))]
#[repr(C)]
struct sigset_t {
    __val: [libc::c_ulong; 16],
}

#[cfg(target_os = "android")]
type sigset_t = libc::c_ulong;

#[cfg(any(target_os = "macos", target_os = "ios"))]
type sigset_t = u32;

#[cfg(any(target_os = "freebsd", target_os = "dragonfly"))]
#[repr(C)]
struct sigset_t {
    bits: [u32; 4],
}

#[cfg(any(target_os = "bitrig", target_os = "netbsd", target_os = "openbsd"))]
type sigset_t = libc::c_uint;