Module Sync.MutexSource

k t is the type of a mutex protecting the contents of the k capsule which can only be held for a bounded period of time.

create k creates a new mutex for the capsule 'k associated with k, consuming the key itself.

The optional padded argument specifies whether to pad the data structure to avoid false sharing. See Atomic.make for a longer explanation.

with_access s t ~f acquires t, runs f within the associated capsule, then releases t. If t is locked then uses s to wait until it is unlocked. The Sync.t is passed to f to allow further use of synchronization primitives.

• raises Poisoned

  if t cannot be acquired because it is poisoned.

try_with_access t ~f is like with_access, but returns Would_block if t is currently locked.

with_access_poisoning s t ~f acquires t, runs f within the associated capsule, then releases t. If t is locked then uses s to wait until it is unlocked. The Sync.t is passed to f to allow further use of synchronization primitives.

Poisons t if f raises an uncaught exception.

• raises Poisoned

  if t cannot be acquired because it is poisoned.

try_with_access_poisoning t ~f is like with_access_poisoning, but returns Would_block if t is currently locked.

with_access_or_cancel s c t f is Completed (with_access s t f) if c is not canceled, otherwise it is Canceled.

with_access_or_cancel_poisoning s c t f is Completed (with_access_poisoning s t f) if c is not canceled, otherwise it is Canceled.

Poisons t if f raises an uncaught exception.

with_password s t f acquires t, runs f with permission to access the associated capsule, then releases t. If t is locked then uses s to wait until it is unlocked. The Sync.t is passed to f to allow further use of synchronization primitives.

• raises Poisoned

  if t cannot be acquired because it is poisoned.

try_with_password t ~f is like with_password, but returns Would_block if t is currently locked.

with_password_poisoning s t f acquires t, runs f with permission to access the associated capsule, then releases t. If t is locked then uses s to wait until it is unlocked. The Sync.t is passed to f to allow further use of synchronization primitives.

Poisons t if f raises an exception.

• raises Poisoned

  if t cannot be acquired because it is poisoned.

try_with_password_poisoning t ~f is like with_password_poisoning, but returns Would_block if t is currently locked.

with_password_or_cancel s c t f is Completed (with_password s t f) if c is not canceled, otherwise it is Canceled.

with_password_or_cancel_poisoning s c t f is Completed (with_password_poisoning s t f) if c is not canceled, otherwise it is Canceled.

Poisons t if f raises an exception.

with_key_poisoning s t ~f locks t and runs f, providing it a key for 'k uniquely. If the function raises without returning the key back, the mutex is poisoned. If t is locked, then with_key_poisoning uses s to wait until it is unlocked. The Sync.t is passed to f to allow further use of synchronization primitives.

There is no non-poisoning version of this function, because you must return the key back (to avoid leaking it via an exception).

• raises Poisoned

  if t cannot be acquired because it is poisoned.

try_with_key t ~f is like with_key, but returns Would_block if t is currently locked.

with_key_or_cancel_poisoning s c t ~f is Completed (with_key_poisoning s t ~f) if c is not canceled, otherwise it is Canceled.

Condition variable for waiting for changes to state protected by a lock.

with_key_and_condition_wait_poisoning w t ~f locks t and runs f, providing it with a key for 'k uniquely and a 'k Condition.Wait.t which provides the ability to temporarily unlock t and wait on an associated 'k Condition.t. Since waiting on a condition variable can delay for an unbounded period of time, this requires an Await.t, even for a Sync mutex, but only passes a Sync.t to the callback. To recover the original Await.t during the execution of f, you can use Condition.Wait.release_temporarily.

The lock is only poisoned if f raises while the lock held; if waiting on a condition variable is terminated or if the callback passed to Condition.Wait.release_temporarily raises, the lock will not be poisoned.

• raises Poisoned

  if t cannot be acquired because it is poisoned.

• raises Terminated

  if w is terminated before the mutex is acquired.

with_key_and_condition_wait_or_cancel_poisoining w c t ~f is Completed (with_key_and_condition_wait_poisoining w t ~f) if c is not canceled, otherwise it is Canceled.

release_temporarily s t k ~f releases t, runs f without the mutex, reacquires t and returns the result of running f along with the k.

To obtain a key to pass to release_temporarily, use with_key or similar functions.

• raises Poisoned

  if t cannot be reacquired because it is poisoned.

release_temporarily_or_cancel s c t k ~f is Completed (release_temporarily s t k ~f) if c is not canceled, otherwise it is Canceled.

poison t key poisons the mutex associated with the key.

acquire_and_poison s t acquires t and then immediately poisons it, returning the key to the protected capsule.

• raises Poisoned

  if t cannot be acquired because it is poisoned.

acquire_and_poison_or_cancel s c t is Completed (acquire_and_poison s t) if c is not canceled, otherwise it is Canceled.

is_poisoned t determines whether the mutex t is poisoned.

is_locked t determines whether the mutex t is locked.

poison_unacquired t poisons t without acquiring it. Does nothing if t is already poisoned.

Note that this can render the capsule associated with t innaccessible, since it potentially destroys the associated key.

A poisonable single word mutual exclusion lock embedded within an atomic location.