Struct Shutdown

pub struct Shutdown { /* private fields */ }

A request guard and future for graceful shutdown.

A server shutdown is manually requested by calling Shutdown::notify() or, if enabled, through automatic triggers like Ctrl-C. Rocket will stop accepting new requests, finish handling any pending requests, wait a grace period before cancelling any outstanding I/O, and return Ok() to the caller of Rocket::launch(). Graceful shutdown is configured via ShutdownConfig.

Detecting Shutdown

Shutdown is also a future that resolves when Shutdown::notify() is called. This can be used to detect shutdown in any part of the application:

use rocket::Shutdown;

#[get("/wait/for/shutdown")]
async fn wait_for_shutdown(shutdown: Shutdown) -> &'static str {
    shutdown.await;
    "Somewhere, shutdown was requested."
}

See the stream docs for an example of detecting shutdown in an infinite responder.

Additionally, a completed shutdown request resolves the future returned from Rocket::launch():

use rocket::Shutdown;

#[get("/shutdown")]
fn shutdown(shutdown: Shutdown) -> &'static str {
    shutdown.notify();
    "Shutting down..."
}

#[rocket::main]
async fn main() {
    let result = rocket::build()
        .mount("/", routes![shutdown])
        .launch()
        .await;

    // If the server shut down (by visiting `/shutdown`), `result` is `Ok`.
    result.expect("server failed unexpectedly");
}

Implementations

impl Shutdown

pub fn notify(&self)

Notify the application to shut down gracefully.

This function returns immediately; pending requests will continue to run until completion or expiration of the grace period, which ever comes first, before the actual shutdown occurs. The grace period can be configured via ShutdownConfig’s grace field.

use rocket::Shutdown;

#[get("/shutdown")]
fn shutdown(shutdown: Shutdown) -> &'static str {
    shutdown.notify();
    "Shutting down..."
}

pub fn notified(&self) -> bool

Returns true if Shutdown::notify() has already been called.

Example

use rocket::Shutdown;

#[get("/shutdown")]
fn shutdown(shutdown: Shutdown) {
    shutdown.notify();
    assert!(shutdown.notified());
}

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 Debug for Shutdown

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

Formats the value using the given formatter.

impl<'r> FromRequest<'r> for Shutdown

type Error = Infallible

The associated error to be returned if derivation fails.

fn from_request<'life0, 'async_trait>( request: &'r Request<'life0>, ) -> Pin<Box<dyn Future<Output = Outcome<Self, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Derives an instance of Self from the incoming request metadata.

impl Future for Shutdown

type Output = ()

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.