Struct Control 

pub struct Control { /* private fields */ }

A handle for shutdown and connection counting that is not tied to an address type.

Unlike Handle, one Control can drive servers listening on different address types, for example TCP and Unix at the same time. Build a Handle for each listener with Handle::with_control, then graceful_shutdown or shutdown drains all of them and connection_count covers every listener.

use axum_server::{Control, Handle};
use std::net::SocketAddr;

let control = Control::new();

let handle = Handle::<SocketAddr>::with_control(control.clone());

Implementations

impl Control

pub fn new() -> Self

Create a new control handle.

Examples found in repository

examples/multiple_listeners.rs (line 11)

async fn main() -> io::Result<()> {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    // One control handle drains every listener below.
    let control = Control::new();
    let mut servers = JoinSet::new();

    let tcp_handle = Handle::<SocketAddr>::with_control(control.clone());
    let tcp =
        axum_server::bind(SocketAddr::from(([127, 0, 0, 1], 3000))).handle(tcp_handle.clone());
    let tcp_service = app.clone().into_make_service();

    servers.spawn(async move { tcp.serve(tcp_service).await });

    #[cfg(unix)]
    let unix_handle = {
        use std::os::unix::net::SocketAddr;

        let path = std::env::temp_dir().join("axum-server-multiple-listeners.sock");
        let _ = std::fs::remove_file(&path);

        let handle = Handle::with_control(control.clone());
        let unix = axum_server::bind(SocketAddr::from_pathname(path)?).handle(handle.clone());
        let service = app.clone().into_make_service();

        servers.spawn(async move { unix.serve(service).await });

        handle
    };

    println!("tcp: http://{}/", tcp_handle.listening().await.unwrap());
    #[cfg(unix)]
    println!(
        "unix: {:?}",
        unix_handle
            .listening()
            .await
            .unwrap()
            .as_pathname()
            .unwrap()
    );

    let shutdown = control.clone();
    tokio::spawn(async move {
        let _ = tokio::signal::ctrl_c().await;
        shutdown.graceful_shutdown(Some(Duration::from_secs(10)));
    });

    // A failing listener stops the others instead of leaving them running.
    while let Some(result) = servers.join_next().await {
        match result {
            Ok(Ok(())) => {}
            Ok(Err(error)) => {
                eprintln!("server error: {error}");
                control.shutdown();
            }
            Err(error) => {
                eprintln!("server task failed: {error}");
                control.shutdown();
            }
        }
    }

    #[cfg(unix)]
    let _ = std::fs::remove_file(std::env::temp_dir().join("axum-server-multiple-listeners.sock"));

    Ok(())
}

pub fn connection_count(&self) -> usize

Get the number of live connections across all servers using this control.

pub fn shutdown(&self)

Shutdown all servers using this control.

Examples found in repository

examples/multiple_listeners.rs (line 61)

async fn main() -> io::Result<()> {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    // One control handle drains every listener below.
    let control = Control::new();
    let mut servers = JoinSet::new();

    let tcp_handle = Handle::<SocketAddr>::with_control(control.clone());
    let tcp =
        axum_server::bind(SocketAddr::from(([127, 0, 0, 1], 3000))).handle(tcp_handle.clone());
    let tcp_service = app.clone().into_make_service();

    servers.spawn(async move { tcp.serve(tcp_service).await });

    #[cfg(unix)]
    let unix_handle = {
        use std::os::unix::net::SocketAddr;

        let path = std::env::temp_dir().join("axum-server-multiple-listeners.sock");
        let _ = std::fs::remove_file(&path);

        let handle = Handle::with_control(control.clone());
        let unix = axum_server::bind(SocketAddr::from_pathname(path)?).handle(handle.clone());
        let service = app.clone().into_make_service();

        servers.spawn(async move { unix.serve(service).await });

        handle
    };

    println!("tcp: http://{}/", tcp_handle.listening().await.unwrap());
    #[cfg(unix)]
    println!(
        "unix: {:?}",
        unix_handle
            .listening()
            .await
            .unwrap()
            .as_pathname()
            .unwrap()
    );

    let shutdown = control.clone();
    tokio::spawn(async move {
        let _ = tokio::signal::ctrl_c().await;
        shutdown.graceful_shutdown(Some(Duration::from_secs(10)));
    });

    // A failing listener stops the others instead of leaving them running.
    while let Some(result) = servers.join_next().await {
        match result {
            Ok(Ok(())) => {}
            Ok(Err(error)) => {
                eprintln!("server error: {error}");
                control.shutdown();
            }
            Err(error) => {
                eprintln!("server task failed: {error}");
                control.shutdown();
            }
        }
    }

    #[cfg(unix)]
    let _ = std::fs::remove_file(std::env::temp_dir().join("axum-server-multiple-listeners.sock"));

    Ok(())
}

pub fn graceful_shutdown(&self, duration: Option<Duration>)

Gracefully shutdown all servers using this control.

None means indefinite grace period.

Examples found in repository

examples/multiple_listeners.rs (line 52)

async fn main() -> io::Result<()> {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    // One control handle drains every listener below.
    let control = Control::new();
    let mut servers = JoinSet::new();

    let tcp_handle = Handle::<SocketAddr>::with_control(control.clone());
    let tcp =
        axum_server::bind(SocketAddr::from(([127, 0, 0, 1], 3000))).handle(tcp_handle.clone());
    let tcp_service = app.clone().into_make_service();

    servers.spawn(async move { tcp.serve(tcp_service).await });

    #[cfg(unix)]
    let unix_handle = {
        use std::os::unix::net::SocketAddr;

        let path = std::env::temp_dir().join("axum-server-multiple-listeners.sock");
        let _ = std::fs::remove_file(&path);

        let handle = Handle::with_control(control.clone());
        let unix = axum_server::bind(SocketAddr::from_pathname(path)?).handle(handle.clone());
        let service = app.clone().into_make_service();

        servers.spawn(async move { unix.serve(service).await });

        handle
    };

    println!("tcp: http://{}/", tcp_handle.listening().await.unwrap());
    #[cfg(unix)]
    println!(
        "unix: {:?}",
        unix_handle
            .listening()
            .await
            .unwrap()
            .as_pathname()
            .unwrap()
    );

    let shutdown = control.clone();
    tokio::spawn(async move {
        let _ = tokio::signal::ctrl_c().await;
        shutdown.graceful_shutdown(Some(Duration::from_secs(10)));
    });

    // A failing listener stops the others instead of leaving them running.
    while let Some(result) = servers.join_next().await {
        match result {
            Ok(Ok(())) => {}
            Ok(Err(error)) => {
                eprintln!("server error: {error}");
                control.shutdown();
            }
            Err(error) => {
                eprintln!("server task failed: {error}");
                control.shutdown();
            }
        }
    }

    #[cfg(unix)]
    let _ = std::fs::remove_file(std::env::temp_dir().join("axum-server-multiple-listeners.sock"));

    Ok(())
}

Trait Implementations

impl Clone for Control

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Control

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

Formats the value using the given formatter.

impl Default for Control

fn default() -> Self

Returns the “default value” for a type.