[][src]Struct signal_hook::iterator::Signals

pub struct Signals { /* fields omitted */ }

The main structure of the module, representing interest in some signals.

Unlike the helpers in other modules, this registers the signals when created and unregisters them on drop. It provides the pending signals during its lifetime, either in batches or as an infinite iterator.

Multiple consumers

You may have noticed this structure can be used simultaneously by multiple threads. If it is done, a signal arrives to one of the threads (on the first come, first serve basis). The signal is not broadcasted to all currently active threads.

A similar thing applies to cloning the structure ‒ at least one of the copies gets the signal, but it is not broadcasted to all of them.

If you need multiple recipients, you can create multiple independent instances (not by cloning, but by the constructor).

Examples

use signal_hook::iterator::Signals;

let signals = Signals::new(&[signal_hook::SIGUSR1, signal_hook::SIGUSR2])?;
thread::spawn(move || {
    for signal in &signals {
        match signal {
            signal_hook::SIGUSR1 => {},
            signal_hook::SIGUSR2 => {},
            _ => unreachable!(),
        }
    }
});

mio support

If the crate is compiled with the mio-support flag, the Signals becomes pluggable into mio (it implements the Evented trait). If it becomes readable, there may be new signals to pick up. The structure is expected to be registered with level triggered mode.

tokio support

If the crate is compiled with the tokio-support flag, the into_async method becomes available. This method turns the iterator into an asynchronous stream of received signals.

Methods

impl Signals
[src]

Turns the iterator into an asynchronous stream.

This allows getting the signals in asynchronous way in a tokio event loop. Available only if compiled with the tokio-support feature enabled.

Examples

extern crate libc;
extern crate signal_hook;
extern crate tokio;

use std::io::Error;

use signal_hook::iterator::Signals;
use tokio::prelude::*;

fn main() -> Result<(), Error> {
    let wait_signal = Signals::new(&[signal_hook::SIGUSR1])?
        .into_async()?
        .into_future()
        .map(|sig| assert_eq!(sig.0.unwrap(), signal_hook::SIGUSR1))
        .map_err(|e| panic!("{}", e.0));
    unsafe { libc::kill(libc::getpid(), signal_hook::SIGUSR1) };
    tokio::run(wait_signal);
    Ok(())
}

Turns the iterator into a stream, tied into a specific tokio reactor.

impl Signals
[src]

Creates the Signals structure.

This registers all the signals listed. The same restrictions (panics, errors) apply as with register.

Important traits for Pending<'a>

Returns an iterator of already received signals.

This returns an iterator over all the signal numbers of the signals received since last time they were read (out of the set registered by this Signals instance). Note that they are returned in arbitrary order and a signal number is returned only once even if it was received multiple times.

This method returns immediately (does not block) and may produce an empty iterator if there are no signals ready.

Important traits for Pending<'a>

Waits for some signals to be available and returns an iterator.

This is similar to pending. If there are no signals available, it tries to wait for some to arrive. However, due to implementation details, this still can produce an empty iterator.

This can block for arbitrary long time.

Note that the blocking is done in this method, not in the iterator.

Important traits for Forever<'a>

Returns an infinite iterator over arriving signals.

The iterator's next() blocks as necessary to wait for signals to arrive. This is adequate if you want to designate a thread solely to handling signals. If multiple signals come at the same time (between two values produced by the iterator), they will be returned in arbitrary order. Multiple instances of the same signal may be collated.

This is also the iterator returned by IntoIterator implementation on &Signals.

Examples

use signal_hook::iterator::Signals;

let signals = Signals::new(&[signal_hook::SIGUSR1, signal_hook::SIGUSR2])?;
thread::spawn(move || {
    for signal in signals.forever() {
        match signal {
            signal_hook::SIGUSR1 => {},
            signal_hook::SIGUSR2 => {},
            _ => unreachable!(),
        }
    }
});

Trait Implementations

impl Clone for Signals
[src]

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

impl<'a> IntoIterator for &'a Signals
[src]

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Important traits for Forever<'a>

Creates an iterator from a value. Read more

impl Drop for Signals
[src]

Executes the destructor for this type. Read more

impl Debug for Signals
[src]

Formats the value using the given formatter. Read more

impl Evented for Signals
[src]

Register self with the given Poll instance. Read more

Re-register self with the given Poll instance. Read more

Deregister self from the given Poll instance Read more

Auto Trait Implementations

impl Send for Signals

impl Sync for Signals

Blanket Implementations

impl<T, U> Into for T where
    U: From<T>, 
[src]

Performs the conversion.

impl<T> ToOwned for T where
    T: Clone
[src]

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

impl<T> From for T
[src]

Performs the conversion.

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from)

Performs the conversion.

impl<T> Borrow for T where
    T: ?Sized
[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut for T where
    T: ?Sized
[src]

Mutably borrows from an owned value. Read more

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from)

Performs the conversion.

impl<T> Any for T where
    T: 'static + ?Sized
[src]

🔬 This is a nightly-only experimental API. (get_type_id)

this method will likely be replaced by an associated static

Gets the TypeId of self. Read more

impl<T> Erased for T