Confusion around sharing State using with_state and Arc (part 2 2025 edition?)

[ColemanDunn]

Summary

Partial resurrection of this issue from 2022. I was browsing the docs and I noticed the section on the main page of the docs that discusses sharing state all use Arc::new(AppState... but the docs for the State struct do not use Arc but instead use #[derive(Clone)] (however the shared mutability section shows using Arc around the individual fields of the state).

Searching which one to use lead me to the 2022 github issue and I share the same/similar confusion around where to use Arc or not. Also, the fix that closed the issue is now outdated/no longer in the main branch/docs. So all that said, which should be used and why/when?

Thanks you!

axum version

0.8.1

[mladedav]

The state must be Clone, axum doesn't really care if it's Arc, AppState where you manually implement Clone or even i32.

It's important to realize that each handler will get a new clone of the state. So if you use a custom struct where you make deep copies, the handlers can't update the data for later handler calls. That (along with cloning Arcs being generally cheap) is why in most use cases you would use an Arc for state.

Does that clear things up for you? Do you have any suggestions on how to improve the documentation?

[ColemanDunn]

The state must be Clone

Ah that makes perfect sense! Thank you! I don't have any suggestions, I was just confused why one section of the docs used Arc exclusively while the other one didn't but that all makes sense under the "The state must be Clone" idea. Thank you!