Struct Swansong

Source

pub struct Swansong { /* private fields */ }

Expand description

§🦢 Shutdown manager

See crate level docs for overview and example.

Two Swansongs are Eq if and only if they are clones of each other.

Implementations§

Source §

impl Swansong

Source

pub fn new() -> Swansong

Construct a new Swansong.

Source

pub fn shut_down(&self) -> ShutdownCompletion

Initiate graceful shutdown.

This will gracefully stop any associated Interrupts.

This returns a ShutdownCompletion type, which can be blocked on with ShutdownCompletion::block or awaited as a Future.

Source

pub fn block_on_shutdown_completion(self)

Blocks the current thread until graceful shutdown is complete

Do not use this in async contexts. Instead, await the Swansong

Source

pub fn state(&self) -> ShutdownState

Determine if this Swansong is running, shutting down, or complete.

Source

pub fn interrupt<T>(&self, wrapped_type: T) -> Interrupt<T>

Wrap any type with an Interrupt, allowing it to cancel or seal on shutdown.

Interrupt<T> has custom implementations of Future, Stream, [AsyncRead][futures_io::AsyncRead], [AsyncWrite][futures_io::AsyncWrite], [AsyncBufRead][futures_io::AsyncBufRead], and Iterator. See further documentation for the behaviors for each of these types at Interrupt.

Each of the trait implementations will behave normally with a small overhead to check shutdown state until shutdown has been initiated with Swansong::shut_down. When shutdown has been initiated, any type inside of an associated Interrupt will be interrupted/canceled/sealed at an appropriate time.

Source

pub fn guard(&self) -> Guard

Returns a new Guard, which forstalls shutdown until it is dropped.

Source

pub fn guard_count(&self) -> usize

The current number of outstanding Guards.

Source

pub fn child(&self) -> Swansong

Create a child Swansong linked to this parent.

The child can be independently shut down without affecting the parent. However, when the parent is shut down, the child will also be shut down. The parent’s shutdown will not be considered complete until the child Swansong and any associated ShutdownCompletions are dropped.

This supports multi-level hierarchies: a child can itself have children, forming a tree. Shutdown propagates downward through the entire tree.

§Performance

Creating a child has O(n) cost where n is the number of live children, due to cleanup of stale internal references. This is suitable for most use cases but may not be ideal for very high-frequency child creation with many concurrent children.

§Example: HTTP/3 server

let server = Swansong::new();

// Each connection gets its own child swansong
let connection = server.child();

// Connection can be shut down independently (e.g., on GOAWAY)
connection.shut_down();

// Or the entire server can shut down, which also stops all connections
// server.shut_down().await;

Source

pub fn guarded<T>(&self, wrapped_type: T) -> Guarded<T>

Attach a guard to the provided type, delaying shutdown until it drops.

This function returns a Guarded wrapper type provides transparent implementations of various traits like Future and Stream, as well as Derefing to the wrapped type. This is identical to moving a Guard into the wrapped type, but sometimes it’s easier to compose the guard around a named future than to move the guard into the future. See Guarded for more information about trait implementations on Guarded