Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท State and Middleware

Shared State in Axum: State, Arc and Mutex

Share data between Axum handlers with State, with_state and FromRef: Arc<Mutex>, RwLock, atomics, database pools, substates, and the Extension alternative.

Handlers are plain functions, and each request runs independently, possibly on a different thread. Yet almost every service needs something shared: a database pool, configuration, an HTTP client, a cache, a counter. Axum's answer is application state: you build one value, attach it to the router with with_state, and ask for it in any handler with the State extractor.

This chapter starts with state, then moves on to middleware. State comes first because middleware and extractors often read it too.

The basic pattern

Rust
use axum::{extract::State, routing::get, Router};
use std::sync::{atomic::{AtomicU64, Ordering}, Arc};

#[derive(Clone)]
struct AppState {
    app_name: String,
    hits: Arc<AtomicU64>,
}

async fn hello(State(state): State<AppState>) -> String {
    let n = state.hits.fetch_add(1, Ordering::Relaxed) + 1;
    format!("{} says hello, visit #{n}", state.app_name)
}

#[tokio::main]
async fn main() {
    let state = AppState {
        app_name: "demo".to_string(),
        hits: Arc::new(AtomicU64::new(0)),
    };

    let app = Router::new()
        .route("/", get(hello))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Three facts to hold on to:

  1. State must be Clone. Axum clones it for every request (or every connection), so cloning must be cheap. That is why the shared parts are wrapped in Arc: cloning an Arc copies a pointer and bumps a counter.
  2. with_state supplies the value. Until you call it, the router has type Router<AppState> ("I still need an AppState"). After .with_state(state) it is Router<()>, which is what axum::serve accepts.
  3. Only handlers that ask get it. A handler without State argument does not see it.

Sharing mutable data

Arc<T> gives shared read access. To change data, add interior mutability:

Need Use
A counter or flag Arc<AtomicU64>, Arc<AtomicBool>
A map or list changed in short critical sections Arc<std::sync::Mutex<T>>
Many readers, few writers Arc<std::sync::RwLock<T>>
A lock that must be held across an .await Arc<tokio::sync::Mutex<T>>
A cache with eviction and expiry a crate such as moka
A database a connection pool (already Clone, no extra Arc), see SQLx pools
Rust
use std::{collections::HashMap, sync::{Arc, Mutex}};

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

async fn add_note(State(state): State<AppState>, body: String) -> String {
    let mut notes = state.notes.lock().unwrap();   // lock...
    let id = notes.len() as u32 + 1;
    notes.insert(id, body);
    format!("saved #{id}")
}                                                   // ...guard dropped at end of scope

Never hold a std::sync::Mutex guard across an .await. The guard is not Send, so the compiler rejects the handler; and even where it compiles (with the Tokio mutex), a long await while holding a lock serialises every request. The recipe is: lock, copy or change what you need, drop the guard, then await. The Tokio lesson discusses this trade-off, including the option of a channel and one owner task.

Several pieces of state with FromRef

Real apps hold a pool, a config and a few services. You could put them all in one AppState and have every handler take the whole struct, but then a handler that only needs the config depends on everything. FromRef lets handlers extract just a part:

Rust
use axum::extract::FromRef;

#[derive(Clone, FromRef)]
struct AppState {
    config: Arc<Config>,
    db: PgPool,
    counter: Arc<AtomicU64>,
}

async fn version(State(config): State<Arc<Config>>) -> String {
    config.version.clone()
}

async fn users(State(db): State<PgPool>) { /* ... */ }

#[derive(FromRef)] generates FromRef<AppState> for each field. Handlers declare only the piece they use, and the same trick lets custom extractors reach into state without knowing its full type.

State with nested and merged routers

Sub-routers that use State<AppState> have type Router<AppState>. You can build them separately and call with_state once at the top:

Rust
fn app(state: AppState) -> Router {
    Router::new()
        .nest("/users", users::router())     // Router<AppState>
        .nest("/posts", posts::router())     // Router<AppState>
        .with_state(state)                   // now Router<()>
}

See nesting and merging. If you call with_state on a sub-router with a different state type, that sub-router is complete (Router<()>) and can be nested anywhere.

State or Extension?

Older code stores shared values with Extension and an Extension layer:

Rust
.layer(Extension(pool))
// handler: Extension(pool): Extension<PgPool>

Prefer State: it is type-checked at compile time. Forget with_state and the code does not compile. Forget the Extension layer and the request fails at run time with a 500. Use Extension for per-request values that middleware computes (such as the authenticated user), see extensions and request ids.

Stand-in: shared state across threads

Handlers run concurrently, so the clearest way to feel state is to run several "requests" at the same time. This program clones an AppState into eight threads; they increment an atomic counter and add notes to a mutex-protected map. The total is exact, which is the guarantee Arc plus a lock or atomic provides.

Rust Stand-in: Arc, Mutex and atomics shared by concurrent handlers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Exactly 2000 hits and 2000 notes, every time. Replace the AtomicU64 with a plain u64 inside the Arc and the compiler refuses the program: Rust makes the missing synchronisation a compile error, not a data race.

Stand-in: FromRef, a handler that takes only what it needs

The second model mirrors #[derive(FromRef)]: one big AppState, a FromRef trait, and handlers that declare only the sub-state they use. A test can then build just that sub-state.

Rust Stand-in: FromRef gives handlers only their part

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Common mistakes

  • Cloning large data into AppState instead of wrapping it in Arc: every request copies it.
  • Holding a lock guard across .await.
  • Wrapping a pool in Arc<Mutex<Pool>>: pools are already internally shared and thread-safe; a mutex around one makes every query wait for the previous one.
  • Forgetting .with_state(...): the compiler error mentions Router<AppState> and serve. Add the call.
  • Storing per-request data in global state. Use extensions for that.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is shared state usually wrapped in Arc?

    AppState must be Clone. Arc makes cloning cheap and lets all clones point at the same data.
  2. 2. What does Router<AppState> mean before with_state is called?

    The type parameter records the state still missing. with_state turns it into Router<()>.
  3. 3. You need to update a HashMap from handlers with short critical sections and no awaits while locked. What fits best?

    A standard mutex is fine for short locks that never cross an await.
  4. 4. What is the main advantage of State over Extension for application-wide values?

    with_state is checked by the type system, whereas a forgotten Extension layer fails when a request arrives.

Summary

  • Build one Clone state value, attach it with with_state, read it with State<T>.
  • Wrap shared data in Arc; add Mutex, RwLock or atomics for mutation, and never hold a std guard across .await.
  • #[derive(FromRef)] lets handlers and extractors take just the substate they need.
  • Prefer State over Extension for app-wide data; use extensions for per-request values.

Next: Middleware with from_fn