Struct Handle 

pub struct Handle<A: Address> { /* private fields */ }

A handle for Server.

It controls the server it is passed to and, through with_control, any number of servers sharing the same Control.

Implementations

impl<A: Address> Handle<A>

pub fn new() -> Self

Create a new handle.

Examples found in repository

examples/shutdown.rs (line 16)

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

    let handle = Handle::new();

    // Spawn a task to shutdown server.
    tokio::spawn(shutdown(handle.clone()));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("listening on {}", addr);
    axum_server::bind(addr)
        .handle(handle)
        .serve(app.into_make_service())
        .await
        .unwrap();

    println!("server is shut down");
}

examples/graceful_shutdown.rs (line 19)

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

    let handle = Handle::new();

    // Spawn a task to gracefully shutdown server.
    tokio::spawn(graceful_shutdown(handle.clone()));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("listening on {}", addr);
    axum_server::bind(addr)
        .handle(handle)
        .serve(app.into_make_service())
        .await
        .unwrap();

    println!("server is shut down");
}

pub fn with_control(control: Control) -> Self

Create a handle that shares shutdown and connection counting with control.

Each server should get its own Handle so that listening reports the address of that server.

Examples found in repository

examples/multiple_listeners.rs (line 14)

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 control(&self) -> Control

Get the shared Control.

pub fn connection_count(&self) -> usize

Get the number of connections.

Examples found in repository

examples/graceful_shutdown.rs (line 48)

async fn graceful_shutdown(handle: Handle<SocketAddr>) {
    // Wait 10 seconds.
    sleep(Duration::from_secs(10)).await;

    println!("sending graceful shutdown signal");

    // Signal the server to shutdown using Handle.
    handle.graceful_shutdown(Some(Duration::from_secs(30)));

    // Print alive connection count every second.
    loop {
        sleep(Duration::from_secs(1)).await;

        println!("alive connections: {}", handle.connection_count());
    }
}

pub fn shutdown(&self)

Shutdown the server.

Examples found in repository

examples/shutdown.rs (line 39)

async fn shutdown(handle: Handle<SocketAddr>) {
    // Wait 20 seconds.
    sleep(Duration::from_secs(20)).await;

    println!("sending shutdown signal");

    // Signal the server to shutdown using Handle.
    handle.shutdown();
}

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

Gracefully shutdown the server.

None means indefinite grace period.

Examples found in repository

examples/graceful_shutdown.rs (line 42)

async fn graceful_shutdown(handle: Handle<SocketAddr>) {
    // Wait 10 seconds.
    sleep(Duration::from_secs(10)).await;

    println!("sending graceful shutdown signal");

    // Signal the server to shutdown using Handle.
    handle.graceful_shutdown(Some(Duration::from_secs(30)));

    // Print alive connection count every second.
    loop {
        sleep(Duration::from_secs(1)).await;

        println!("alive connections: {}", handle.connection_count());
    }
}

pub async fn listening(&self) -> Option<A>

Returns local address and port when server starts listening.

Returns None if server fails to bind.

Examples found in repository

examples/multiple_listeners.rs (line 37)

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<A: Clone + Address> Clone for Handle<A>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<A: Debug + Address> Debug for Handle<A>

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

Formats the value using the given formatter.

impl<A: Address> Default for Handle<A>

fn default() -> Self

Returns the “default value” for a type.