itsscb/axum
1
0
Fork 0
mirror of https://github.com/tokio-rs/axum.git synced 2025-10-02 15:24:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation about sharing state with handlers (#3333)

Browse Source
This commit is contained in:
Jonas Platte 2025-04-30 10:03:16 +02:00 committed by GitHub
parent 53631b2873
commit 80c4eadd82
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 14 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
axum/src/lib.rs
View File

@ -148,10 +148,12 @@
//! pool of database connections or clients to other services may need to //! pool of database connections or clients to other services may need to
//! be shared. //! be shared.
//! //!
//! The three most common ways of doing that are: //! The four most common ways of doing that are:
//!
//! - Using the [`State`] extractor //! - Using the [`State`] extractor
//! - Using request extensions //! - Using request extensions
//! - Using closure captures //! - Using closure captures
//! - Using task-local variables
//! //!
//! ## Using the [`State`] extractor //! ## Using the [`State`] extractor
//! //!
@ -182,13 +184,13 @@
//! ``` //! ```
//! //!
//! You should prefer using [`State`] if possible since it's more type safe. The downside is that //! You should prefer using [`State`] if possible since it's more type safe. The downside is that
//! it's less dynamic than request extensions. //! it's less dynamic than task-local variables and request extensions.
//! //!
//! See [`State`] for more details about accessing state. //! See [`State`] for more details about accessing state.
//! //!
//! ## Using request extensions //! ## Using request extensions
//! //!
//! Another way to extract state in handlers is using [`Extension`](crate::extract::Extension) as //! Another way to share state with handlers is using [`Extension`](crate::extract::Extension) as
//! layer and extractor: //! layer and extractor:
//! //!
//! ```rust,no_run //! ```rust,no_run
@ -273,12 +275,11 @@
//! # let _: Router = app; //! # let _: Router = app;
//! ``` //! ```
//! //!
//! The downside to this approach is that it's a little more verbose than using //! The downside to this approach is that it's a the most verbose approach.
//! [`State`] or extensions.
//! //!
//! ## Using [tokio's `task_local` macro](https://docs.rs/tokio/1/tokio/macro.task_local.html): //! ## Using task-local variables
//! //!
//! This allows to share state with `IntoResponse` implementations. //! This also allows to share state with `IntoResponse` implementations:
//! //!
//! ```rust,no_run //! ```rust,no_run
//! use axum::{ //! use axum::{
@ -337,6 +338,12 @@
//! .route_layer(middleware::from_fn(auth)); //! .route_layer(middleware::from_fn(auth));
//! ``` //! ```
//! //!
//! The main downside to this approach is that it only works when the async executor being used
//! has the concept of task-local variables. The example above uses
//! [tokio's `task_local` macro](https://docs.rs/tokio/1/tokio/macro.task_local.html).
//! smol does not yet offer equivalent functionality at the time of writing (see
//! [this GitHub issue](https://github.com/smol-rs/async-executor/issues/139)).
//!
//! # Building integrations for axum //! # Building integrations for axum
//! //!
//! Libraries authors that want to provide [`FromRequest`], [`FromRequestParts`], or //! Libraries authors that want to provide [`FromRequest`], [`FromRequestParts`], or