Module Nano_mutex
A nano-mutex is a lightweight mutex that can be used only within a single OCaml runtime.
Performance
Nano-mutexes are intended to be significantly cheaper than OS-level mutexes. Creating a nano-mutex allocates a single OCaml record. Locking and unlocking an uncontested nano-mutex each take a handful of instructions. Only if a nano-mutex is contested will it fall back to using an OS-level mutex. If a nano-mutex becomes uncontested again, it will switch back to using an OCaml-only lock.
Nano-mutexes can be faster than using OS-level mutexes because OCaml uses a global lock on the runtime, and requires all running OCaml code to hold the lock. The OCaml compiler only allows thread switches at certain points, and we can use that fact to get the atomic test-and-set used in the core of our implementation without needing any primitive locking, essentially because we're protected by the OCaml global lock.
Here are some benchmarks comparing various mutexes available in OCaml (run in 2020-03):
|----------------------------------|----------|---------| | Name | Time/Run | mWd/Run | |----------------------------------|----------|---------| | Caml.Mutex create | 42.1 ns | 3.00w | | Caml.Mutex lock/unlock | 23.6 ns | | | Error_checking_mutex create | 47.2 ns | 3.00w | | Error_checking_mutex lock/unlock | 25.6 ns | | | Nano_mutex create | 4.4 ns | 4.00w | | Nano_mutex lock/unlock | 12.3 ns | | |-------------------------------------------------------|
The benchmark code is in core/extended/lib_test/bench_nano_mutex.ml.
Error handling
For any mutex, there are design choices as to how to behave in certain situations:
- recursive locking (when a thread locks a mutex it already has)
- unlocking an unlocked mutex
- unlocking a mutex held by another thread
Here is a table comparing how the various mutexes behave:
|--------------------+------------+------------+------------+ | | Caml.Mutex | Core.Mutex | Nano_mutex | |--------------------+------------+------------+------------+ | recursive lock | undefined | error | error | | unlocking unlocked | undefined | error | error | | t1:lock t2:unlock | undefined | error | error | |--------------------+------------+------------+------------+
val sexp_of_t : t -> Ppx_sexp_conv_lib.Sexp.t
val current_thread_has_lock : t -> bool
current_thread_has_lock t
returnstrue
iff the current thread hast
locked.
val lock : t -> unit Core_kernel.Or_error.t
lock t
locks the mutext
, blocking until it can be locked.lock
immediately returnsError
if the current thread already holdst
.
val lock_exn : t -> unit
val try_lock : t -> [ `Acquired | `Not_acquired ] Core_kernel.Or_error.t
try_lock t
lockst
if it can immediately do so. The result indicates whethertry_lock
succeeded in acquiring the lock.try_lock
returnsError
if the current thread already holdst
.
val try_lock_exn : t -> [ `Acquired | `Not_acquired ]
val unlock : t -> unit Core_kernel.Or_error.t
unlock t
unlockst
, if the current thread holds it.unlock
returnsError
if the lock is not held by the calling thread.