Struct ShutdownManager

pub struct ShutdownManager<T: Clone> { /* private fields */ }

Shutdown manager for asynchronous tasks and futures.

The shutdown manager allows you to:

• Signal futures to shutdown or forcibly cancel them (by dropping them).
• Wait for futures to perform their clean-up after a shutdown was triggered.
• Retrieve the shutdown reason after the shutdown was triggered.

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

Implementations

impl<T: Clone> ShutdownManager<T>

pub fn new() -> Self

Create a new shutdown manager.

pub fn is_shutdown_triggered(&self) -> bool

Check if the shutdown has been triggered.

pub fn is_shutdown_completed(&self) -> bool

Check if the shutdown has completed.

pub fn shutdown_reason(&self) -> Option<T>

Get the shutdown reason, if the shutdown has been triggered.

Returns None if the shutdown has not been triggered yet.

pub fn wait_shutdown_triggered(&self) -> ShutdownSignal<T>

Asynchronously wait for the shutdown to be triggered.

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

If the 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().

pub fn wait_shutdown_complete(&self) -> ShutdownComplete<T>

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 WrapDelayShutdown futures have completed or are dropped.

pub fn trigger_shutdown( &self, reason: T, ) -> Result<(), ShutdownAlreadyStarted<T>>

Trigger the shutdown.

This will cause all ShutdownSignal and WrapCancel futures associated with this shutdown manager to be resolved.

The shutdown will not be considered complete until all DelayShutdownTokens are dropped.

If the shutdown was already started, this function returns an error.

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

Wrap a future so that it is cancelled (dropped) when the shutdown is triggered.

The returned future completes with Err(shutdown_reason) if the shutdown is triggered, and with Ok(x) if the wrapped future completes first.

pub fn wrap_trigger_shutdown<F: Future>( &self, shutdown_reason: T, future: F, ) -> WrapTriggerShutdown<T, F>

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

pub fn wrap_delay_shutdown<F: Future>( &self, future: F, ) -> Result<WrapDelayShutdown<T, F>, ShutdownAlreadyCompleted<T>>

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

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

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

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

Get a token that delays shutdown completion as long as it exists.

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_delay_shutdown() instead.

pub fn trigger_shutdown_token( &self, shutdown_reason: T, ) -> TriggerShutdownToken<T>

Get a token that triggers a shutdown when dropped.

When a TriggerShutdownToken is dropped, the shutdown is triggered automatically. This applies to any token. If you clone a token five times and drop one of them, it will trigger a shutdown/

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

Trait Implementations

impl<T: Clone + Clone> Clone for ShutdownManager<T>

fn clone(&self) -> ShutdownManager<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Clone> Default for ShutdownManager<T>

fn default() -> Self

Returns the “default value” for a type.