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 ooof. I assume this applies to futures::lock::Mutex, too?...
@zkat Yes, looks like it. Basically async and mutexes just don't play along, because futures can always be cancelled (dropped) at any await point
@rain I feel like the concept of a mutex just isn't as general in async rust and I wonder what new things we need instead.
Like, I'm using lilos mutexes heavily for the first time in a project right now, and having something like that is great for e.g. fair shared access to a driver. But I've had to make all my drivers cancel safe as a result.
Message-passing often winds up needing a heap to resolve ownership issues, ruling it out for me.
I feel like we need something new.
@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 @rain wasn't parking_lot one of the things they were considering merging into std?
@Lunaphied @rain yes but i think it got cancelled on account of the std mutexes getting plain old rewritten instead
@leftpaddotpy @rain huh, we'll have to look at the new implementation then. Honestly I thought std::Mutex was fairly decently written if simplistic
@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
@leftpaddotpy @rain fully onboard with avoiding mutexen, but, does the std mutex still run the risk of blocking / sleeping the executor task? such a nightmare to debug when a dependency contains a lock that breaks the runtime.
@r @rain yes, but if you're holding a mutex for an appreciable period of time for a pure, no-io, task, that's a separate problem imo. In that case, the program design should probably be rethought to have a worker thread and message passing.
Another thought: a reason this could happen is deadlocking cross-task. But if you use std mutex, the guard is !Send so that's basically impossible to do since you cannot hold it over await points.
In the cases where I use them, they are very uncontended.
@rain Hm what are the alternatives? You obviously will never always have lock-free structures. Are Rwlock thingies better?
@MTRNord For Tokio mutexes, the main alternative is a message passing design
@MTRNord (Note I don't have a problem with synchronous mutexes)
@rain this is really interesting, thank you! Hope the guide will be public because it sounds like it will be worth reading.