Struct ShutdownManager 

pub struct ShutdownManager { /* private fields */ }

A top level structure responsible for controlling process shutdown by listening to the underlying registered signals and issuing cancellation to tasks derived from its root cancellation token.

Implementations

impl ShutdownManager

pub fn build_new_default() -> Result<Self>

Create new instance of ShutdownManager with the most sensible defaults, so that:

• shutdown will be triggered upon either SIGINT, SIGTERM (unix only) or SIGQUIT (unix only) being sent
• shutdown will be triggered upon any task panicking

pub fn with_shutdown<F>(self, shutdown: F) -> Self

where F: Future<Output = ()> + Send + 'static,

Register a new shutdown signal that upon completion will trigger system shutdown.

pub fn with_legacy_task_manager(self) -> Self

Include support for the legacy TaskManager to this instance of the ShutdownManager. This will allow issuing TaskClient for tasks that still require them.

pub fn with_shutdown_signal(self, signal_kind: SignalKind) -> Result<Self>

Add the specified signal to the currently registered shutdown signals that will trigger cancellation of all registered tasks.

pub fn with_terminate_signal(self) -> Result<Self>

Add the SIGTERM signal to the currently registered shutdown signals that will trigger cancellation of all registered tasks.

pub fn with_quit_signal(self) -> Result<Self>

Add the SIGQUIT signal to the currently registered shutdown signals that will trigger cancellation of all registered tasks.

pub fn with_default_shutdown_signals(self) -> Result<Self>

Add default signals to the set of the currently registered shutdown signals that will trigger cancellation of all registered tasks. This includes SIGINT, SIGTERM and SIGQUIT for unix-based platforms and SIGINT for other targets (such as windows)/

pub fn with_interrupt_signal(self) -> Self

Add the SIGINT (ctrl-c) signal to the currently registered shutdown signals that will trigger cancellation of all registered tasks.

pub fn spawn<F>(&self, task: F) -> JoinHandle<F::Output>

where F: Future + Send + 'static, F::Output: Send + 'static,

Spawn the provided future on the current Tokio runtime, and track it in the underlying TaskTracker.

pub fn try_spawn_named<F>(&self, task: F, name: &str) -> JoinHandle<F::Output>

where F: Future + Send + 'static, F::Output: Send + 'static,

Spawn the provided future on the current Tokio runtime, and track it in the underlying TaskTracker. Furthermore, attach a name to the spawned task to more easily track it within a tokio console

Note that is no different from spawn if the underlying binary has not been built with RUSTFLAGS="--cfg tokio_unstable" and --features="tokio-tracing"

pub fn spawn_on<F>(&self, task: F, handle: &Handle) -> JoinHandle<F::Output>

where F: Future + Send + 'static, F::Output: Send + 'static,

Spawn the provided future on the provided Tokio runtime, and track it in the underlying TaskTracker.

pub fn spawn_local<F>(&self, task: F) -> JoinHandle<F::Output>

where F: Future + 'static, F::Output: 'static,

Spawn the provided future on the current LocalSet, and track it in the underlying TaskTracker.

pub fn spawn_blocking<F, T>(&self, task: F) -> JoinHandle<T>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Spawn the provided blocking task on the current Tokio runtime, and track it in the underlying TaskTracker.

pub fn spawn_blocking_on<F, T>(&self, task: F, handle: &Handle) -> JoinHandle<T>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Spawn the provided blocking task on the provided Tokio runtime, and track it in the underlying TaskTracker.

pub fn try_spawn_named_with_shutdown<F>( &self, task: F, name: &str, ) -> JoinHandle<Result<F::Output, Cancelled>>

where F: Future + Send + 'static, F::Output: Send + 'static,

Spawn the provided future on the current Tokio runtime that will get cancelled once a global shutdown signal is detected, and track it in the underlying TaskTracker.

Note that to fully use the naming feature, such as tracking within a tokio console, the underlying binary has to be built with RUSTFLAGS="--cfg tokio_unstable" and --features="tokio-tracing"

pub fn spawn_with_shutdown<F>( &self, task: F, ) -> JoinHandle<Result<F::Output, Cancelled>>

where F: Future + Send + 'static, F::Output: Send + 'static,

Spawn the provided future on the current Tokio runtime that will get cancelled once a global shutdown signal is detected, and track it in the underlying TaskTracker.

impl ShutdownManager

pub fn new_without_signals() -> Self

Create new instance of ShutdownManager without any external shutdown signals registered, meaning it will only attempt to wait for all tasks spawned on its tracker to gracefully finish execution.

pub fn new_from_external_shutdown_token(shutdown_token: ShutdownToken) -> Self

Create new instance of the ShutdownManager using an external shutdown token.

Note: it will not listen to any external shutdown signals! You might want further customise it with shutdown signals (or just use the default set. Similarly, you might want to include cancellation on panic to make sure everything gets cancelled if one of the tasks panics.

pub fn empty_mock() -> Self

Create an empty testing mock of the ShutdownManager with no signals registered.

pub fn with_cancel_on_panic(self) -> Self

Add additional panic hook such that upon triggering, the root ShutdownToken gets cancelled. Note: an unfortunate limitation of this is that graceful shutdown will no longer be possible since that task that has panicked will not exit and thus all shutdowns will have to be either forced or will have to time out.

pub fn with_shutdown_duration(self, duration: Duration) -> Self

Change the maximum shutdown duration when tracked tasks could gracefully exit before forcing the shutdown.

pub fn is_cancelled(&self) -> bool

Returns true if the root ShutdownToken has been cancelled.

pub fn shutdown_tracker(&self) -> &ShutdownTracker

Get a reference to the used ShutdownTracker

pub fn shutdown_tracker_owned(&self) -> ShutdownTracker

Get a cloned instance of the used ShutdownTracker

pub async fn wait_for_tracker(&self)

Waits until the underlying TaskTracker is both closed and empty.

If the underlying TaskTracker is already closed and empty when this method is called, then it returns immediately.

pub fn close_tracker(&self) -> bool

Close the underlying TaskTracker.

This allows wait_for_tracker futures to complete. It does not prevent you from spawning new tasks.

Returns true if this closed the underlying TaskTracker, or false if it was already closed.

pub fn reopen_tracker(&self) -> bool

Reopen the underlying TaskTracker.

This prevents wait_for_tracker futures from completing even if the underlying TaskTracker is empty.

Returns true if this reopened the underlying TaskTracker, or false if it was already open.

pub fn is_tracker_closed(&self) -> bool

Returns true if the underlying TaskTracker is closed.

pub fn tracked_tasks(&self) -> usize

Returns the number of tasks tracked by the underlying TaskTracker.

pub fn is_tracker_empty(&self) -> bool

Returns true if there are no tasks in the underlying TaskTracker.

pub fn child_shutdown_token(&self) -> ShutdownToken

Obtain a ShutdownToken that is a child of the root token

pub fn clone_shutdown_token(&self) -> ShutdownToken

Obtain a ShutdownToken on the same hierarchical structure as the root token

pub fn subscribe_legacy<S: Into<String>>(&self, child_suffix: S) -> TaskClient

👎Deprecated

Attempt to create a handle to a legacy [TaskClient] to support tasks that hasn’t migrated from the legacy [TaskManager]. Note. To use this method ShutdownManager must be built with .with_legacy_task_manager()

pub fn detach_shutdown_signals(&mut self) -> ShutdownSignals

Remove the current set of ShutdownSignals from this instance of ShutdownManager replacing it with an empty set.

This is potentially useful if one wishes to start listening for the signals before the whole process has been fully set up.

pub fn replace_shutdown_signals(&mut self, signals: ShutdownSignals)

Replace the current set of ShutdownSignals used for determining whether the underlying process should be stopped.

pub fn send_cancellation(&self)

Send cancellation signal to all registered tasks by cancelling the root token and sending shutdown signal, if applicable, on the legacy [TaskManager]

pub async fn wait_for_shutdown_signal(&mut self)

Wait until receiving one of the registered shutdown signals this method is cancellation safe

pub async fn perform_shutdown(&mut self)

Perform system shutdown by sending relevant signals and waiting until either:

• all tracked tasks have terminated
• timeout has been reached
• shutdown has been forced (by sending SIGINT)

pub async fn run_until_shutdown(&mut self)

Wait until a shutdown signal has been received and trigger system shutdown.

Trait Implementations

impl Default for ShutdownManager

Available on non-WebAssembly only.

fn default() -> Self

Returns the “default value” for a type.