Module Picos_std_sync.Rwlock

A poisonable, freezable, read-write lock.

🏎ī¸ This uses a low overhead, optimistic, and unfair implementation that also does not perform runtime ownership error checking. In most cases this should be the read-write lock you will want to use and should give roughly equal or better performance than Lock in cases where the majority of operations are reads.

🐌 This is a "slim" lock. Acquiring the lock in read mode has low overhead, but limited scalability. For highly parallel use cases you will either want to use sharding or a "fat" scalable read-write lock.

⚠ī¸ The current implementation allows readers to bypass the queue and does not prevent writers from starvation. For example, a pair of readers running concurrently, acquiring and releasing the lock such that there is never a point where the lock is fully released, prevents writers from acquiring the lock. This might be changed in the future such that neither readers nor writers should starve assuming no single party holds the lock indefinitely.

See also Lock, and Mutex.

type t

Represents a read-write lock.

Basic API

val create : ?padded:bool -> unit -> t

create () returns a new read-write lock that is initially unlocked.

exception Poisoned

Exception raised in case the read-write lock has been poisoned.

val sharing : t -> (unit -> 'a) -> 'a

sharing rwlock thunk acquires a shared hold on the rwlock and calls thunk (). Whether thunk () returns a value or raises an exception, the shared hold on the rwlock will be released.

A single fiber may acquire a shared hold on a specific rwlock multiple times and other fibers may concurrently acquire shared holds on the rwlock as well.

exception Frozen

Exception raised in case the read-write lock has been frozen.

val holding : t -> (unit -> 'a) -> 'a

holding rwlock thunk acquires an exclusive hold on the rwlock and calls thunk (). In case thunk () returns a value, the read-write lock is released and the value is returned. Otherwise the read-write lock will be poisoned and the exception reraised.

val freeze : t -> unit

freeze rwlock marks a rwlock as frozen, which means that one can no longer acquire an exclusive hold on the rwlock.

ℹī¸ No exclusive hold can be obtained on a frozen lock.

🐌 Freezing a rwlock does not improve the scalability of acquiring shared hold on the rwlock.

val protect : t -> (unit -> 'a) -> 'a

protect rwlock thunk acquires an exclusive hold on the rwlock, runs thunk (), and releases the rwlock after thunk () returns or raises.

module Condition : sig ... end

A condition variable.

State query API

val is_locked_shared : t -> bool

is_locked_shared rwlock determines whether the rwlock is currently held shared or not.

⚠ī¸ is_locked_shared rwlock will return false in case the rwlock is held exclusively.

val is_frozen : t -> bool

is_frozen rwlock determines whether the rwlock has been frozen.

val is_locked : t -> bool

is_locked rwlock determines whether the rwlock is currently held exclusively or not.

⚠ī¸ is_locked rwlock will return false in case the rwlock is held shared.

val is_poisoned : t -> bool

is_poisoned rwlock determines whether the rwlock has been poisoned.

Expert API

⚠ī¸ The calls in this section must be matched correctly or the state of the read-write lock may become corrupted.

val acquire_shared : t -> unit

acquire_shared rwlock acquires a shared hold on the rwlock.

A single fiber may acquire a shared hold on a specific rwlock multiple times and other fibers may concurrently acquire shared holds on the rwlock as well.

val try_acquire_shared : t -> bool

try_acquire_shared rwlock attempts to acquire a shared hold on the rwlock. Returns true in case of success and false in case of failure.

val release_shared : t -> unit

release_shared rwlock releases one shared hold on the rwlock or does nothing in case the rwlock has been poisoned.

val acquire : t -> unit

acquire rwlock acquires an exclusive hold on the rwlock.

A fiber may acquire an exclusive hold on a specific rwlock once at a time.

val try_acquire : t -> bool

try_acquire rwlock attempts to acquire an exclusive hold on the rwlock. Returns true in case of success and false in case of failure.

val release : t -> unit

release rwlock releases the exclusive hold on the rwlock or does nothing in case the rwlock has been frozen or poisoned.

val poison : t -> unit

poison rwlock marks an exclusively held rwlock as poisoned.

ℹī¸ Neither shared nor exclusive hold can be obtained on a poisoned lock.

  • raises Invalid_argument

    in case the rwlock is not currently write locked.