Struct async_shutdown::Shutdown

pub struct Shutdown { /* private fields */ }

Shutdown manager for asynchronous tasks and futures.

The shutdown manager serves two separate but related purposes:

• To signal futures to shutdown or forcibly cancel them (by dropping them).
• To wait for futures to perform their clean-up after a shutdown was triggered.

The shutdown manager can be cloned and shared with multiple tasks. Each clone uses the same internal state.

Implementations

impl Shutdown

pub fn new() -> Self

Create a new shutdown manager.

pub fn shutdown_started(&self) -> bool

Check if the shutdown has been started.

pub fn shutdown_completed(&self) -> bool

Check if the shutdown has been completed.

pub fn wait_shutdown_triggered(&self) -> ShutdownSignal

Asynchronously wait for a shutdown to be triggered.

This returns a future that completes when a shutdown is triggered. The future can be cloned and sent to other threads or tasks freely.

If a shutdown is already triggered, the returned future immediately resolves.

You can also use ShutdownSignal::wrap_cancel() of the returned object to automatically cancel a future when the shutdown signal is received. This is identical to Self::wrap_cancel(), but can be done if you only have a ShutdownSignal.

pub fn wait_shutdown_complete(&self) -> ShutdownComplete

Asynchronously wait for the shutdown to complete.

This returns a future that completes when the shutdown is complete. The future can be cloned and sent to other threads or tasks freely.

The shutdown is complete when all DelayShutdownToken are dropped and all WrapWait futures have completed.

pub fn shutdown(&self)

Start the shutdown.

This will complete all ShutdownSignal and WrapCancel futures associated with this shutdown manager.

The shutdown will not complete until all registered futures complete.

If the shutdown was already started, this function is a no-op.

pub fn wrap_cancel<F: Future>(&self, future: F) -> WrapCancel<F>

Wrap a future so that it is cancelled when a shutdown is triggered.

The returned future completes with None when a shutdown is triggered, and with Some(x) when the wrapped future completes.

The wrapped future is dropped when the shutdown starts before the future completed. If the wrapped future completes before the shutdown signal arrives, it is not dropped.

pub fn wrap_vital<F: Future>(&self, future: F) -> WrapVital<F>

Wrap a future to cause a shutdown when it completes or is dropped.

pub fn wrap_wait<F: Future>( &self, future: F ) -> Result<WrapWait<F>, ShutdownAlreadyCompleted>

Wrap a future to delay shutdown completion until it completes or is dropped.

The returned future transparently completes with the value of the wrapped future. However, the shutdown will not be considered complete until the future completes or is dropped.

If the shutdown has already completed, this function returns an error.

pub fn delay_shutdown_token( &self ) -> Result<DelayShutdownToken, ShutdownAlreadyCompleted>

Get a token to delay shutdown completion.

The manager keeps track of all the tokens it hands out. The tokens can be cloned and sent to different threads and tasks. All tokens (including the clones) must be dropped before the shutdown is considered to be complete.

If the shutdown has already completed, this function returns an error.

If you want to delay the shutdown until a future completes, consider using Self::wrap_wait() instead.

pub fn vital_token(&self) -> VitalToken

Get a token that represents a vital task or future.

When a VitalToken is dropped, the shutdown is triggered automatically. This applies to any token. If you clone a token five times and drop one a shutdown is triggered, even though four tokens still exist.

You can also use Self::wrap_vital() to wrap a future so that a shutdown is triggered when the future completes or if it is dropped.

Trait Implementations

impl Clone for Shutdown

fn clone(&self) -> Shutdown

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Shutdown

fn default() -> Self

Returns the “default value” for a type.