Skip to content
rusthacks.dev
Web

Sharing State Between Axum Handlers With State and Arc

Share a pool, config and caches with Axum's State extractor. Learn why the state must be Clone, when to use Arc and how to mutate shared data safely.

8 min read
Summarize in AI
Flat illustration for the post “Sharing State Between Axum Handlers With State and Arc”, composed around threads.

Every real service has something the handlers share: a database pool, a configuration struct, an HTTP client, a cache, a counter. Axum does not use globals for this. It threads one value of a type you choose through the router and hands a clone to each handler that asks for it. The mechanism is simple, and its one real trap, a lock held across an .await, produces a compiler error long enough to scare people off. This post builds a service with config, a counter and a mutable store, shows the failure and the two correct fixes, and explains when to reach for something other than a mutex. Everything compiled with axum 0.8.9 and tokio 1 on Rust 1.99.

State is a clone handed to each handler

src/main.rsrust
use std::{
    collections::HashMap,
    sync::{
        Arc, Mutex,
        atomic::{AtomicU64, Ordering},
    },
};

use axum::{
    Json, Router,
    extract::{FromRef, Path, State},
    http::StatusCode,
    routing::{get, post},
};

#[derive(Clone)]
struct AppState {
    config: Arc<Config>,
    counters: Arc<Counters>,
    notes: Arc<Mutex<HashMap<u32, String>>>,
}

struct Config {
    greeting: String,
}

#[derive(Default)]
struct Counters {
    hits: AtomicU64,
}

#[derive(Clone)]
struct Greeting(String);

impl FromRef<AppState> for Greeting {
    fn from_ref(state: &AppState) -> Self {
        Greeting(state.config.greeting.clone())
    }
}

async fn hello(State(Greeting(g)): State<Greeting>, State(s): State<AppState>) -> String {
    let n = s.counters.hits.fetch_add(1, Ordering::Relaxed) + 1;
    format!("{g}, visitor {n}")
}

async fn put_note(State(s): State<AppState>, Path(id): Path<u32>, body: String) -> StatusCode {
    s.notes.lock().unwrap().insert(id, body);
    StatusCode::NO_CONTENT
}

async fn get_note(State(s): State<AppState>, Path(id): Path<u32>) -> Result<String, StatusCode> {
    s.notes.lock().unwrap().get(&id).cloned().ok_or(StatusCode::NOT_FOUND)
}

async fn count(State(s): State<AppState>) -> Json<usize> {
    Json(s.notes.lock().unwrap().len())
}

#[tokio::main]
async fn main() {
    let state = AppState {
        config: Arc::new(Config { greeting: "hello".into() }),
        counters: Arc::new(Counters::default()),
        notes: Arc::new(Mutex::new(HashMap::new())),
    };
    let app = Router::new()
        .route("/", get(hello))
        .route("/notes", get(count))
        .route("/notes/{id}", post(put_note).get(get_note))
        .with_state(state);
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
Shell
curl -s localhost:3000/
curl -s localhost:3000/
curl -s -X POST localhost:3000/notes/1 -d 'buy milk' -w '%{http_code}\n'
curl -s localhost:3000/notes/1
curl -s -i localhost:3000/notes/9 | head -1
Text
hello, visitor 1
hello, visitor 2
204
buy milk
HTTP/1.1 404 Not Found

Three ideas are at work. The state type derives Clone, because Axum clones it for every request; every field is behind an Arc, so a clone is three reference-count increments and not a copy of the map. .with_state(state) consumes the value and turns the Router<AppState> into a Router<()>, the type axum::serve accepts; forget it and the compiler complains about a router that is still waiting for its state. And the State extractor asks for the type by name, so a handler that requests State<Other> where the router carries AppState is a compile error and not a runtime surprise.

Give a handler only what it needs

hello above takes two State arguments, one of them a Greeting. That works because of the FromRef impl: Axum can produce any type that implements FromRef<AppState>, so a handler can depend on the configuration without seeing the notes map. The payoff is in tests and in code review, where a handler's signature now says what it touches. For simple cases derive it instead of writing it: #[derive(FromRef)] on the state struct (the macros feature) generates an implementation for each field, so State<Arc<Counters>> just works. Keep one rule for yourself: sub-states that need mutation must be shared pointers, because from_ref hands out a clone.

The lock across an await

The mutex above is std::sync::Mutex, correct for a map that is read and written in microseconds. The mistake that every Axum user makes once is holding its guard while awaiting something. Add a call to a slow dependency while the lock is held:

src/main.rsrust
#[debug_handler]
async fn put_note(State(s): State<AppState>, Path(id): Path<u32>, body: String) -> StatusCode {
    let mut notes = s.notes.lock().unwrap();
    tokio::time::sleep(std::time::Duration::from_millis(1)).await;
    notes.insert(id, body);
    StatusCode::NO_CONTENT
}
Text
error: future cannot be sent between threads safely
  --> src/main.rs:47:1
   |
47 | #[debug_handler]
   | ^^^^^^^^^^^^^^^^ future returned by `put_note` is not `Send`
   |
   = help: within `impl Future<Output = StatusCode>`, the trait `Send` is not implemented for `std::sync::MutexGuard<'_, HashMap<u32, String>>`
note: future is not `Send` as this value is used across an await
  --> src/main.rs:50:61
   |
49 |     let mut notes = s.notes.lock().unwrap();
   |         --------- has type `std::sync::MutexGuard<'_, HashMap<u32, String>>` which is not `Send`
50 |     tokio::time::sleep(std::time::Duration::from_millis(1)).await;
   |                                                             ^^^^^ await occurs here, with `mut notes` maybe used later

The compiler is protecting you from a real hazard. Axum runs handlers on Tokio's multi-threaded runtime, so a future may resume on a different thread after an await, and a std mutex guard must be dropped on the thread that locked it. Even if it were allowed, holding a blocking lock across an await would let one slow request stall every task that needs the lock. The first fix is to not hold it across the await at all, which is almost always the right shape:

src/main.rsrust
async fn put_note(State(s): State<AppState>, Path(id): Path<u32>, body: String) -> StatusCode {
    tokio::time::sleep(std::time::Duration::from_millis(1)).await; // slow work first
    {
        let mut notes = s.notes.lock().unwrap();
        notes.insert(id, body);
    } // guard dropped here, before any later await
    StatusCode::NO_CONTENT
}

Do the asynchronous work first, take the lock for the few lines that touch the data, and let the guard drop at the end of the block. If a decision genuinely depends on data under the lock and a later await, copy out what you need (let value = notes.get(&id).cloned();), drop the guard, then await. The second fix is tokio::sync::Mutex, whose guard is Send and whose lock() is itself async. Use it only when the lock really must span an await, such as serializing access to a connection, and accept the cost: it is slower for short critical sections and queues waiters fairly. The comparison, with the benchmarks, is in Tokio mutex versus std mutex.

When a mutex is the wrong tool

You wantUse
A counter or flagAtomicU64 or AtomicBool; no lock at all, as hits above
Read-mostly data, rare writesRwLock, or arc-swap to publish a new immutable snapshot
A database or HTTP connection poolthe pool itself is already shareable; put it in state directly
Work handed to a background taska tokio::sync::mpsc channel, so handlers never block on the worker
Fan-out to many listenerstokio::sync::broadcast or watch

The last two rows are the design choice that matters most. A handler that pushes to a channel returns immediately and the worker owns the data, which removes the lock and the contention with it; Tokio channels compared picks between the types. For a map that every request writes, a sharded structure such as dashmap reduces contention but changes the semantics around holding references, so measure before adopting it.

Testing and construction

Because state is an ordinary value, tests build their own and call the router directly, with no global to reset. Keep construction in one function, AppState::new(config), used by both main and the tests, and the handlers stay free of environment reads. The test approach with a router and no network is in testing with Tower oneshot. Remember that state is shared per router, not per connection or per request: anything request-scoped, like the authenticated user, belongs in a request extension set by middleware (middleware with Tower layers).

Initializing state that can fail

State is built once at startup, and building it often involves work that can fail: connecting to a database, reading a file, parsing configuration. Do that in main before the router exists and let a failure stop the process, instead of constructing partial state and discovering the problem on the first request:

src/main.rsrust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let greeting = std::env::var("GREETING").unwrap_or_else(|_| "hello".into());
    if greeting.len() > 32 {
        return Err("GREETING is longer than 32 bytes".into());
    }

    let state = AppState {
        config: Arc::new(Config { greeting }),
        counters: Arc::new(Counters::default()),
        notes: Arc::new(Mutex::new(HashMap::new())),
    };

    let app = Router::new().route("/", get(hello)).with_state(state);
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

A process that exits at startup with a clear message is a better failure than one that starts, passes the load balancer's health check and then returns 500 on every request. The same rule applies to a database pool: connect, run a trivial query and only then build the router. Fail-fast at boot also makes the problem visible in the deploy log, where the person watching the rollout will see it. Anything that may legitimately change after startup (a feature flag, a rotating credential) does not belong in this immutable struct; put it behind an ArcSwap or a watch channel so handlers read the current value without a lock.

When shared mutable state is the wrong design

An in-process map is lost on restart and not shared across instances, so it suits a cache, a rate-limit table or a single-node demo, and is wrong for anything that must survive a deploy or run behind a load balancer; that belongs in a database or Redis. Keep the state struct small and made of handles to those services, and the layout in an Axum production service shows the arrangement at full size.

Taggedaxumstate
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.