package core_unix

You can search for identifiers within the package.

in-package search v0.2.0

core_unix
- Core_unix
core_unix.bigbuffer_blocking
- Core_unix_bigbuffer_blocking
core_unix.bigstring_unix
- Core_unix_bigstring_unix
core_unix.command_unix
- Command_unix
core_unix.core_thread
- Core_thread
core_unix.daemon
- Core_unix_daemon
core_unix.date_unix
- Date_unix
core_unix.error_checking_mutex
- Core_unix_error_checking_mutex
core_unix.filename_unix
- Filename_unix
core_unix.interval_lib
- Interval_lib
core_unix.iobuf_unix
- Core_unix_iobuf_unix
core_unix.linux_ext
- Core_unix_linux_ext
core_unix.lock_file_blocking
- Core_unix_lock_file_blocking
core_unix.nano_mutex
- Core_unix_nano_mutex
core_unix.process_env
- Core_unix_process_env
core_unix.signal_unix
- Signal_unix
core_unix.squeue
- Core_unix_squeue
core_unix.sys_unix
- Sys_unix
core_unix.syslog
- Core_unix_syslog
core_unix.time_interface
- Time_interface
core_unix.time_ns_unix
- Time_ns_unix
core_unix.time_stamp_counter
- Core_unix_time_stamp_counter
core_unix.time_unix
- Time_unix
core_unix.uuid_unix
- Core_unix_uuid_unix

Legend:
Library
Module
Module type
Parameter
Class
Class type

include module type of struct include Nano_mutex end

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      |
      |--------------------+------------+------------+------------+

type t = Nano_mutex.t

val sexp_of_t : t -> Ppx_sexp_conv_lib.Sexp.t

val invariant : t -> unit

val create : unit -> t

create () returns a new, unlocked mutex.

val equal : t -> t -> bool

equal is phys_equal

val current_thread_has_lock : t -> bool

current_thread_has_lock t returns true iff the current thread has t locked.

val lock : t -> unit Core_kernel.Or_error.t

lock t locks the mutex t, blocking until it can be locked. lock immediately returns Error if the current thread already holds t.

val lock_exn : t -> unit

val try_lock : t -> [ `Acquired | `Not_acquired ] Core_kernel.Or_error.t

try_lock t locks t if it can immediately do so. The result indicates whether try_lock succeeded in acquiring the lock. try_lock returns Error if the current thread already holds t.

val try_lock_exn : t -> [ `Acquired | `Not_acquired ]

val unlock : t -> unit Core_kernel.Or_error.t

unlock t unlocks t, if the current thread holds it. unlock returns Error if the lock is not held by the calling thread.

val unlock_exn : t -> unit

val critical_section : t -> f:(unit -> 'a) -> 'a