[−][src]Struct signal_hook::iterator::Signals
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
or mio-0_7-support
flags, the Signals
becomes pluggable into mio
version 0.6
or 0.7
respectively (it implements the Source
trait). If it becomes readable, there may be new signals to pick up.
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.
Implementations
impl Signals
[src]
pub fn into_async(self) -> Result<Async, Error>
[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::raise(signal_hook::SIGUSR1) }; tokio::run(wait_signal); Ok(()) }
pub fn into_async_with_handle(self, handle: &Handle) -> Result<Async, Error>
[src]
Turns the iterator into a stream, tied into a specific tokio reactor.
impl Signals
[src]
pub fn new<I, S>(signals: I) -> Result<Self, Error> where
I: IntoIterator<Item = S>,
S: Borrow<c_int>,
[src]
I: IntoIterator<Item = S>,
S: Borrow<c_int>,
Creates the Signals
structure.
This registers all the signals listed. The same restrictions (panics, errors) apply as with
register
.
pub fn add_signal(&self, signal: c_int) -> Result<(), Error>
[src]
Registers another signal to the set watched by this Signals
instance.
Notes
- This is safe to call concurrently from whatever thread.
- This is not safe to call from within a signal handler.
- If the signal number was already registered previously, this is a no-op.
- If this errors, the original set of signals is left intact.
- This actually registers the signal into the whole group of
Signals
cloned from each other, so any of them might start receiving the signals.
Panics
- If the given signal is forbidden.
- If the signal number is negative or larger than internal limit. The limit should be larger than any supported signal the OS supports.
pub fn pending(&self) -> Pending<'_>ⓘ
[src]
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.
pub fn wait(&self) -> Pending<'_>ⓘ
[src]
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.
pub fn forever(&self) -> Forever<'_>ⓘ
[src]
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
.
This iterator terminates only if the Signals
is explicitly closed.
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!(), } } });
pub fn is_closed(&self) -> bool
[src]
Is it closed?
See close
.
pub fn close(&self)
[src]
Closes the instance.
This is meant to signalize termination through all the interrelated instances ‒ the ones
created by cloning the same original Signals
instance (and all the Async
ones
created from them). After calling close:
is_closed
will return true.- All currently blocking operations on all threads and all the instances are interrupted and terminate.
- Any further operations will never block.
- Further signals may or may not be returned from the iterators. However, if any are returned, these are real signals that happened.
- The
forever
terminates (follows from the above).
The goal is to be able to shut down any background thread that handles only the signals.
let signals = Signals::new(&[SIGUSR1])?; let signals_bg = signals.clone(); let thread = std::thread::spawn(move || { for signal in &signals_bg { // Whatever with the signal } }); signals.close(); // The thread will terminate on its own now (the for cycle runs out of signals). thread.join().expect("background thread panicked");
Trait Implementations
impl Clone for Signals
[src]
impl Debug for Signals
[src]
impl Evented for Signals
[src]
pub fn register(
&self,
poll: &Poll,
token: Token,
interest: Ready,
opts: PollOpt
) -> Result<(), Error>
[src]
&self,
poll: &Poll,
token: Token,
interest: Ready,
opts: PollOpt
) -> Result<(), Error>
pub fn reregister(
&self,
poll: &Poll,
token: Token,
interest: Ready,
opts: PollOpt
) -> Result<(), Error>
[src]
&self,
poll: &Poll,
token: Token,
interest: Ready,
opts: PollOpt
) -> Result<(), Error>
pub fn deregister(&self, poll: &Poll) -> Result<(), Error>
[src]
impl<'a> IntoIterator for &'a Signals
[src]
type Item = c_int
The type of the elements being iterated over.
type IntoIter = Forever<'a>
Which kind of iterator are we turning this into?
pub fn into_iter(self) -> Forever<'a>ⓘ
[src]
impl Source for Signals
[src]
Auto Trait Implementations
impl RefUnwindSafe for Signals
[src]
impl Send for Signals
[src]
impl Sync for Signals
[src]
impl Unpin for Signals
[src]
impl UnwindSafe for Signals
[src]
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,