broker_tokio::signal::unix

Struct Signal

Source
pub struct Signal { /* private fields */ }
Available on crate feature signal only.
Expand description

A stream of events for receiving a particular type of OS signal.

In general signal handling on Unix is a pretty tricky topic, and this structure is no exception! There are some important limitations to keep in mind when using Signal streams:

  • Signals handling in Unix already necessitates coalescing signals together sometimes. This Signal stream is also no exception here in that it will also coalesce signals. That is, even if the signal handler for this process runs multiple times, the Signal stream may only return one signal notification. Specifically, before poll is called, all signal notifications are coalesced into one item returned from poll. Once poll has been called, however, a further signal is guaranteed to be yielded as an item.

    Put another way, any element pulled off the returned stream corresponds to at least one signal, but possibly more.

  • Signal handling in general is relatively inefficient. Although some improvements are possible in this crate, it’s recommended to not plan on having millions of signal channels open.

If you’ve got any questions about this feel free to open an issue on the repo! New approaches to alleviate some of these limitations are always appreciated!

§Caveats

The first time that a Signal instance is registered for a particular signal kind, an OS signal-handler is installed which replaces the default platform behavior when that signal is received, for the duration of the entire process.

For example, Unix systems will terminate a process by default when it receives SIGINT. But, when a Signal instance is created to listen for this signal, the next SIGINT that arrives will be translated to a stream event, and the process will continue to execute. Even if this Signal instance is dropped, subsequent SIGINT deliveries will end up captured by Tokio, and the default platform behavior will NOT be reset.

Thus, applications should take care to ensure the expected signal behavior occurs as expected after listening for specific signals.

§Examples

Wait for SIGHUP

use tokio::signal::unix::{signal, SignalKind};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // An infinite stream of hangup signals.
    let mut stream = signal(SignalKind::hangup())?;

    // Print whenever a HUP signal is received
    loop {
        stream.recv().await;
        println!("got signal HUP");
    }
}

Implementations§

Source§

impl Signal

Source

pub async fn recv(&mut self) -> Option<()>

Receive the next signal notification event.

None is returned if no more events can be received by this stream.

§Examples

Wait for SIGHUP

use tokio::signal::unix::{signal, SignalKind};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // An infinite stream of hangup signals.
    let mut stream = signal(SignalKind::hangup())?;

    // Print whenever a HUP signal is received
    loop {
        stream.recv().await;
        println!("got signal HUP");
    }
}
Source

pub fn poll_recv(&mut self, cx: &mut Context<'_>) -> Poll<Option<()>>

Poll to receive the next signal notification event, outside of an async context.

None is returned if no more events can be received by this stream.

§Examples

Polling from a manually implemented future

use std::pin::Pin;
use std::future::Future;
use std::task::{Context, Poll};
use tokio::signal::unix::Signal;

struct MyFuture {
    signal: Signal,
}

impl Future for MyFuture {
    type Output = Option<()>;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        println!("polling MyFuture");
        self.signal.poll_recv(cx)
    }
}

Trait Implementations§

Source§

impl Debug for Signal

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Stream for Signal

Available on crate feature stream only.
Source§

type Item = ()

Values yielded by the stream.
Source§

fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<()>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted. Read more
Source§

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream. Read more

Auto Trait Implementations§

§

impl !Freeze for Signal

§

impl !RefUnwindSafe for Signal

§

impl Send for Signal

§

impl Sync for Signal

§

impl Unpin for Signal

§

impl !UnwindSafe for Signal

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

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

Source§

impl<St> StreamExt for St
where St: Stream + ?Sized,

Source§

fn next(&mut self) -> Next<'_, Self>
where Self: Unpin,

Available on crate feature stream only.
Consumes and returns the next value in the stream or None if the stream is finished. Read more
Source§

fn try_next<T, E>(&mut self) -> TryNext<'_, Self>
where Self: Stream<Item = Result<T, E>> + Unpin,

Available on crate feature stream only.
Consumes and returns the next item in the stream. If an error is encountered before the next item, the error is returned instead. Read more
Source§

fn map<T, F>(self, f: F) -> Map<Self, F>
where F: FnMut(Self::Item) -> T, Self: Sized,

Available on crate feature stream only.
Maps this stream’s items to a different type, returning a new stream of the resulting type. Read more
Source§

fn merge<U>(self, other: U) -> Merge<Self, U>
where U: Stream<Item = Self::Item>, Self: Sized,

Available on crate feature stream only.
Combine two streams into one by interleaving the output of both as it is produced. Read more
Source§

fn filter<F>(self, f: F) -> Filter<Self, F>
where F: FnMut(&Self::Item) -> bool, Self: Sized,

Available on crate feature stream only.
Filters the values produced by this stream according to the provided predicate. Read more
Source§

fn filter_map<T, F>(self, f: F) -> FilterMap<Self, F>
where F: FnMut(Self::Item) -> Option<T>, Self: Sized,

Available on crate feature stream only.
Filters the values produced by this stream while simultaneously mapping them to a different type according to the provided closure. Read more
Source§

fn fuse(self) -> Fuse<Self>
where Self: Sized,

Available on crate feature stream only.
Creates a stream which ends after the first None. Read more
Source§

fn take(self, n: usize) -> Take<Self>
where Self: Sized,

Available on crate feature stream only.
Creates a new stream of at most n items of the underlying stream. Read more
Source§

fn take_while<F>(self, f: F) -> TakeWhile<Self, F>
where F: FnMut(&Self::Item) -> bool, Self: Sized,

Available on crate feature stream only.
Take elements from this stream while the provided predicate resolves to true. Read more
Source§

fn all<F>(&mut self, f: F) -> AllFuture<'_, Self, F>
where Self: Unpin, F: FnMut(Self::Item) -> bool,

Available on crate feature stream only.
Tests if every element of the stream matches a predicate. Read more
Source§

fn any<F>(&mut self, f: F) -> AnyFuture<'_, Self, F>
where Self: Unpin, F: FnMut(Self::Item) -> bool,

Available on crate feature stream only.
Tests if any element of the stream matches a predicate. Read more
Source§

fn chain<U>(self, other: U) -> Chain<Self, U>
where U: Stream<Item = Self::Item>, Self: Sized,

Available on crate feature stream only.
Combine two streams into one by first returning all values from the first stream then all values from the second stream. Read more
Source§

fn collect<T>(self) -> Collect<Self, T>
where T: FromStream<Self::Item>, Self: Sized,

Available on crate feature stream only.
Drain stream pushing all emitted values into a collection. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.