Struct Swansong 

pub struct Swansong { /* private fields */ }

🦢 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

impl Swansong

pub fn new() -> Swansong

Construct a new Swansong.

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.

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

pub fn state(&self) -> ShutdownState

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

pub fn shutting_down(&self) -> ShuttingDown

Returns a ShuttingDown future that resolves when shutdown has been initiated on this Swansong.

This does not initiate shutdown — it only observes the transition from ShutdownState::Running to ShutdownState::ShuttingDown. The future resolves as soon as Swansong::shut_down is called (on this handle or any parent), or when the last root handle is dropped.

The returned future does not wait for outstanding Guards to drop. To wait for full shutdown (stopped and all guards dropped), use Swansong::shut_down or Swansong::into_future.

ShuttingDown can also be used in blocking contexts via ShuttingDown::block.

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.

pub fn guard(&self) -> Guard

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

pub fn guard_count(&self) -> usize

The total number of outstanding Guards in this Swansong’s subtree.

For a root or leaf Swansong with no children, this is just the Guards created via this Swansong (and its clones). For a Swansong with children, it is the sum of Guards held in this node plus all Guards in all descendant subtrees. Child Swansong handles themselves are not counted as Guards; only real Guard instances are.

This performs an O(subtree) walk; prefer not to call it in a hot path.

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;

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

Trait Implementations

impl AsRef<Swansong> for HttpContext

fn as_ref(&self) -> &Swansong

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Swansong

fn clone(&self) -> Swansong

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Swansong

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Swansong

fn default() -> Swansong

Returns the “default value” for a type.

impl Drop for Swansong

If we are dropping the last Swansong handle to a root node, stop the associated futures. Dropping the last handle to a child (non-root) node does not signal shutdown: the parent remains the governing authority, and the child stays in its current state until the parent propagates stop or until all Guards in the child’s subset naturally drain.

fn drop(&mut self)

Executes the destructor for this type.

impl IntoFuture for Swansong

type Output = ()

The output that the future will produce on completion.

type IntoFuture = ShutdownCompletion

Which kind of future are we turning this into?

fn into_future(self) -> <Swansong as IntoFuture>::IntoFuture

Creates a future from a value.

impl PartialEq for Swansong

fn eq(&self, other: &Swansong) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Swansong