Recent searches
Search options
![Don’t use tokio::sync::Mutex
(Or, shared mutable state is bad.)
Tokio comes with a Mutex that is specifically designed for use in asynchronous contexts. The official recommendation is to prefer std::sync::Mutex if locks are not held across await points, and tokio::sync::Mutex only if locks are held across awaits.
However, given that:
Almost all uses of mutexes are to temporarily violate code invariants within a critical section, restoring them by the end of the operation.
Mutexes are almost always shared between futures (otherwise why would a mutex be used at all), which means that the "cancellation blast radius" of a future holding a mutex extends to other futures.
std::sync::Mutex has a notion of lock poisoning. Tokio’s mutexes don’t[12].
What this suggests is that if a future that is currently holding on to a mutex is cancelled, the state guarded by the mutex is likely invalid. This is such a big problem that this guide recommends avoiding tokio::sync::Mutex to the greatest extent possible.
Alternatives to Tokio mutexes
The main alternative to a Tokio mutex is a message-passing design, as described in this Tokio tutorial. Rather than having futures access some common shared state, this scheme has a single manager task that has full (non-shared) ownership of this state. This task receives requests in serial order, via an MPSC channel, and sends responses over (typically) oneshot channels.](https://media.hachyderm.io/media_attachments/files/110/737/372/462/814/674/original/aa86e5b7918c99e0.png "Don’t use tokio::sync::Mutex
(Or, shared mutable state is bad.)
Tokio comes with a Mutex that is specifically designed for use in asynchronous contexts. The official recommendation is to prefer std::sync::Mutex if locks are not held across await points, and tokio::sync::Mutex only if locks are held across awaits.
However, given that:
Almost all uses of mutexes are to temporarily violate code invariants within a critical section, restoring them by the end of the operation.
Mutexes are almost always shared between futures (otherwise why would a mutex be used at all), which means that the \"cancellation blast radius\" of a future holding a mutex extends to other futures.
std::sync::Mutex has a notion of lock poisoning. Tokio’s mutexes don’t[12].
What this suggests is that if a future that is currently holding on to a mutex is cancelled, the state guarded by the mutex is likely invalid. This is such a big problem that this guide recommends avoiding tokio::sync::Mutex to the greatest extent possible.
Alternatives to Tokio mutexes
The main alternative to a Tokio mutex is a message-passing design, as described in this Tokio tutorial. Rather than having futures access some common shared state, this scheme has a single manager task that has full (non-shared) ownership of this state. This task receives requests in serial order, via an MPSC channel, and sends responses over (typically) oneshot channels.")
![Another alternative is to switch to std::sync::Mutex if possible, and not hold locks across await points. In many cases this can be done through some kind of code rearrangement or a few judicious clones.
If you really must use a Tokio mutex
It isn’t impossible to write correct code that manages Tokio mutexes, just very difficult. Some approaches you could take:
Declare that your code isn’t cancel-safe.
Ensure that invariants are always restored between await points. Having invalid state between await points is okay[13].
Clean up invalid state at the start of every critical section.
All of these options require you to think a lot, which isn’t true for any of the recommended suggestions.](https://media.hachyderm.io/media_attachments/files/110/737/375/795/838/244/original/7cab16bc8fa1a650.png "Another alternative is to switch to std::sync::Mutex if possible, and not hold locks across await points. In many cases this can be done through some kind of code rearrangement or a few judicious clones.
If you really must use a Tokio mutex
It isn’t impossible to write correct code that manages Tokio mutexes, just very difficult. Some approaches you could take:
Declare that your code isn’t cancel-safe.
Ensure that invariants are always restored between await points. Having invalid state between await points is okay[13].
Clean up invalid state at the start of every critical section.
All of these options require you to think a lot, which isn’t true for any of the recommended suggestions.")
@rain yes, in general async sync primitives seem to be a sign of bugs. async state probably should only be held by one task or instead made into sync state. i have not deadlocked myself with sync primitives (in particular because of very limited critical section lengths) but i have dealt with async ones deadlocking which is also impossible to debug comparatively.
@rain I was also contemplating submitting a change to the tokio docs to stop suggesting parking_lot also, because the std mutex really is fine now for basically all use cases, and parking_lot may be only a slight improvement.
@leftpaddotpy Correct, the parking lot mutex should not be recommended because it doesn't do lock poisoning.
@rain https://github.com/tokio-rs/website/pull/714 alright, I suppose I will submit it then :D