Eio.Mutex
Mutual exclusion.
A mutex can be used to ensure that only one piece of code can access a shared resource at one time.
Unlike Stdlib.Mutex
, which blocks the whole domain while waiting to take the mutex, this module allows other Eio fibers to run while waiting. You should use this module if your critical section may perform blocking operations, while Stdlib.Mutex
may be more efficient if the lock is held only briefly and the critial section does not switch fibers.
Note that mutexes are often unnecessary for code running in a single domain, as the scheduler will only switch to another fiber if you perform an operation that can block.
type t = Mutex.t
The type for a concurrency-friendly mutex.
val create : unit -> t
create ()
creates an initially unlocked mutex.
val use_rw : protect:bool -> t -> (unit -> 'a) -> 'a
use_rw ~protect t fn
waits for the mutex to be free and then executes fn ()
while holding the mutex locked. fn
may mutate the resource protected by the mutex, but must ensure the resource is in a consistent state before returning. If fn
raises an exception, the mutex is disabled and cannot be used again.
val use_ro : t -> (unit -> 'a) -> 'a
use_ro t fn
is like use_rw ~protect:false
, but if fn
raises an exception it unlocks the mutex instead of disabling it. Use this if you only need read-only access to the mutex's resource and so know that it will be in a consistent state even if an exception is raised.
Note: a mutex still only allows one fiber to have the mutex locked at a time, even if all operations are "read-only".
Care must be taken when locking a mutex manually. It is easy to forget to unlock it in some cases, which will result in deadlock the next time a fiber tries to use it. In particular, you need to consider:
val lock : t -> unit
Lock the given mutex. Only one fiber can have the mutex locked at any time. A fiber that attempts to lock a mutex already locked by another fiber will suspend until the other fiber unlocks the mutex. If no other fiber has the lock, this returns immediately without switching fibers.
val unlock : t -> unit
unlock t
unlocks the mutex.