Module Await.AwaitableSource

An awaitable atomic reference to a value of type 'a.

make v creates a new awaitable atomic reference with the given initial value v.

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

get t gets the current value of the awaitable atomic reference.

set t v sets a new value v for the awaitable atomic reference.

exchange t v sets a new value v for the awaitable atomic reference and returns the current value.

compare_and_set t ~if_phys_equal_to:seen ~replace_with:v sets the new value of t to v only if its current value is physically equal to seen -- the comparison and the set occur atomically. Returns true if the comparison succeeded (so the set happened) and false otherwise.

compare_exchange t ~if_phys_equal_to:seen ~replace_with:v sets the new value of s to v only if its current value is physically equal to seen -- the comparison and the set occur atomically. Returns the previous value.

fetch_and_add t n atomically increments the value of t by n, and returns the current value (before the increment).

incr t atomically increments the value of t by 1.

decr t atomically decrements the value of t by 1.

update t ~pure_f atomically updates t to be the result of pure_f (get t). pure_f may be called multiple times, so should be free of side effects.

get_and_update t ~pure_f atomically updates t to be the result of pure_f (get t). pure_f may be called multiple times, so should be free of side effects. Returns the old value.

Result of await or await_or_cancel.

await w t ~until_phys_unequal_to:v suspends the caller until the awaitable t is explicitly signaled and/or has a value physically unequal to v.

The return value is Signaled in case the await was woken up due to a signal or broadcast on the awaitable. Otherwise the return value is Terminated.

This operation is subject to the ABA problem. An await for a value other than A may not return after the awaitable is signaled while having the value B, because at a later point the awaitable has again the value A. Furthermore, by the time an await for value other than A returns, the awaitable might already again have the value A.

Atomic operations that change the value of an awaitable do not implicitly wake up awaiters.

await establishes a happens-before relationship with any reads and writes on the current thread that precede it, and the comparison of the current value of the awaitable t with the given value v.

await_or_cancel w c t ~until_phys_unequal_to:v is like await w t ~until_phys_unequal_to:v, but the caller will also be resumed in case the cancellation token c becomes canceled.

The return value is Signaled in case the await was woken up due to a signal or broadcast on the awaitable. Otherwise the return value is either Terminated in case w is terminated, and Canceled in case c is canceled.

signal t tries to wake up at least one awaiter on the awaitable location t.

broadcast t tries to wake up all the awaiters on the awaitable location t.

An expert interface that allows an await to be setup separately from suspending the thread of control. This makes it possible to e.g. implement condition variables, which requires setting up the await before unlocking the associated mutex, and also makes it possible to await for one of many things.

random_key t is the random key assigned to the awaitable t at construction time. The random key is not guaranteed to be unique.