pub struct SignalsInfo<E: Exfiltrator = SignalOnly>(_);
Expand description

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.

Most users will want to use it through the Signals type alias for simplicity.

Multiple threads

Instances of this struct can be sent to other threads. In a multithreaded application this can be used to dedicate a separate thread for signal handling. In this case you should get a Handle using the handle method before sending the Signals instance to a background thread. With the handle you will be able to shut down the background thread later, or to operatively add more signals.

The controller handle can be shared between as many threads as you like using its clone method.

Exfiltrators

The [SignalOnly] provides only the signal number. There are further exfiltrators available in the exfiltrator module. Note that some of them are behind feature flags that need to be enabled.

Examples

use signal_hook::consts::signal::*;
use signal_hook::iterator::Signals;

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

// Some time later...
handle.close();
thread.join().unwrap();

Implementations

Creates the Signals structure.

This registers all the signals listed. The same restrictions (panics, errors) apply as for the Handle::add_signal method.

An advanced constructor with explicit Exfiltrator.

Registers another signal to the set watched by this Signals instance.

The same restrictions (panics, errors) apply as for the Handle::add_signal method.

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 instance may 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.

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. If the Handle::close method is used in another thread this method will return immediately.

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

Is it closed?

See close.

Get 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 &mut Signals.

This iterator terminates only if explicitly closed.

Examples
use signal_hook::consts::signal::*;
use signal_hook::iterator::Signals;

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

Get a shareable handle to a Handle for this instance.

This can be used to add further signals or close the Signals instance.

Trait Implementations

Formats the value using the given formatter. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.