Struct actix_rt::signal::unix::Signal [−][src]
pub struct Signal { /* fields omitted */ }
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, theSignal
stream may only return one signal notification. Specifically, beforepoll
is called, all signal notifications are coalesced into one item returned frompoll
. Oncepoll
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
Receives 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");
}
}
Polls 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
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
Auto Trait Implementations
impl !RefUnwindSafe for Signal
impl !UnwindSafe for Signal
Blanket Implementations
Mutably borrows from an owned value. Read more
Creates a future that resolves to the next item in the stream. Read more
Maps this stream’s items to a different type, returning a new stream of the resulting type. Read more
Creates a stream which gives the current iteration count as well as the next value. Read more
Filters the values produced by this stream according to the provided asynchronous predicate. Read more
Filters the values produced by this stream while simultaneously mapping them to a different type according to the provided asynchronous closure. Read more
Computes from this stream’s items new items of a different type using an asynchronous closure. Read more
Transforms a stream into a collection, returning a future representing the result of that computation. Read more
Converts a stream of pairs into a future, which resolves to pair of containers. Read more
Concatenate all items of a stream into a single extendable destination, returning a future representing the end result. Read more
Drives the stream to completion, counting the number of items. Read more
Execute an accumulating asynchronous computation over a stream, collecting all the values into one final result. Read more
Execute predicate over asynchronous stream, and return true
if any element in stream satisfied a predicate. Read more
Execute predicate over asynchronous stream, and return true
if all element in stream satisfied a predicate. Read more
Flattens a stream of streams into just one continuous stream. Read more
Maps a stream like StreamExt::map
but flattens nested Stream
s. Read more
Combinator similar to StreamExt::fold
that holds internal state
and produces a new stream. Read more
Skip elements on this stream while the provided asynchronous predicate
resolves to true
. Read more
Take elements from this stream while the provided asynchronous predicate
resolves to true
. Read more
Take elements from this stream until the provided future resolves. Read more
Runs this stream to completion, executing the provided asynchronous closure for each element on the stream. Read more
Runs this stream to completion, executing the provided asynchronous closure for each element on the stream concurrently as elements become available. Read more
Creates a new stream of at most n
items of the underlying stream. Read more
Creates a new stream which skips n
items of the underlying stream. Read more
Catches unwinding panics while polling the stream. Read more
Wrap the stream in a Box, pinning it. Read more
Wrap the stream in a Box, pinning it. Read more
An adaptor for creating a buffered list of pending futures. Read more
An adaptor for creating a buffered list of pending futures (unordered). Read more
An adapter for zipping two streams together. Read more
Adapter for chaining two streams. Read more
An adaptor for chunking up items of the stream inside a vector. Read more
An adaptor for chunking up ready items of the stream inside a vector. Read more
A future that completes after the given stream has been fully processed into the sink and the sink has been flushed and closed. Read more
Splits this Stream + Sink
object into separate Sink
and Stream
objects. Read more
Do something with each item of this stream, afterwards passing it on. Read more
Wrap this stream in an Either
stream, making it the left-hand variant
of that Either
. Read more
Wrap this stream in an Either
stream, making it the right-hand variant
of that Either
. Read more
A convenience method for calling Stream::poll_next
on Unpin
stream types. Read more
Consumes and returns the next value in the stream or None
if the
stream is finished. Read more
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
Maps this stream’s items to a different type, returning a new stream of the resulting type. Read more
Combine two streams into one by interleaving the output of both as it is produced. Read more
Filters the values produced by this stream according to the provided predicate. Read more
Filters the values produced by this stream while simultaneously mapping them to a different type according to the provided closure. Read more
Creates a new stream of at most n
items of the underlying stream. Read more
Take elements from this stream while the provided predicate
resolves to true
. Read more
Creates a new stream that will skip the n
first items of the
underlying stream. Read more
Skip elements from the underlying stream while the provided predicate
resolves to true
. Read more
Tests if every element of the stream matches a predicate. Read more
Tests if any element of the stream matches a predicate. Read more
Combine two streams into one by first returning all values from the first stream then all values from the second stream. Read more
A combinator that applies a function to every element in a stream producing a single, final value. Read more
Drain stream pushing all emitted values into a collection. Read more