barrier-wait Function

Summary

Waits on a barrier until enough threads arrive.

Package

mp

Signature

barrier-wait barrier &key timeout callback pass-through discount-on-abort discount-on-timeout disable-on-unblock => result

Arguments

Values

Description

The function barrier-wait waits on a barrier until enough threads arrive on barrier. When barrier-wait is called, it "arrives", and when the number of arrivers reaches the count of the barrier (that is, the count argument to make-barrier), barrier-wait returns. Effectively, the last "arriver" unblocks the barrier and wakes up all the other waiting threads.

timeout is the maximum time to wait in seconds.

If pass-through is true, barrier-wait performs the other operations but does not wait.

discount-on-abort controls whether to change the arrivers count of barrier on an abort (see later).

discount-on-timeout controls whether to change the arrivers count of barrier on a timeout (see later).

disable-on-unblock controls whether to disable barrier when unblocking.

callback, if supplied, specifies a callback called before unblocking.

barrier-wait first checks whether barrier is disabled, and if it is then barrier-wait returns nil immediately. It then checks the number of arrivers of barrier, which is the number of other calls to barrier-wait on the same barrier since it was last unblocked or created.

If the number of arrivers is less than the count minus 1, barrier-wait increases the number of arrivers by 1, and then waits for barrier to be unblocked (unless pass-through is true, which causes it to return immediately). If the number of arrivers of barrier equals its count minus 1, then barrier-wait unblocks barrier (as described below) and returns :unblocked.

discount-on-abort, discount-on-timeout, disable-on-unblock and callback allow you to control how barrier-wait waits and also how barrier is unblocking. For each of these, the effective value is either that supplied to barrier-wait, or if it was not supplied to barrier-wait, the value in barrier itself (see make-barrier).

timeout can be used to limit the time that barrier-wait waits. It is either a number of seconds or nil (the default), meaning wait forever. If barrier-wait times out, it returns :timeout. By default it does not change the number of arrivers after a timeout, so the call is still counted as an "arrival", but this can be changed by using discount-on-timeout. If discount-on-timeout is true then barrier-wait decrements the arrivers count after a timeout, so the call has no overall effect on the arrivers count.

If barrier-wait is aborted while it waits (for example by process-terminate or throwing using process-interrupt), it does not change the arrivers count by default, so the call still counts as an arrival, but this can be changed by using discount-on-abort. If discount-on-abort is true, then barrier-wait decrements the arrivers count on aborting, so the call has no overall effect on the arrivers count.

If barrier-wait would have waited but pass-through is true, it returns the symbol :passed-through instead of waiting. Hence a call to barrier-wait with a true value of pass-through has the effect of incrementing the arriver count, and unblocking other waiters if needed, but never itself waiting.

Unblocking a barrier: when the number of arrivers at barrier equals its count minus 1, barrier-wait "unblocks the barrier". This involves the following steps:

1. If callback is non-nil, it is called with barrier while holding an internal lock in the barrier. See the comment in make-barrier. If callback aborts, nothing will have been changed in barrier (including no change to the number of arrivers).
2. barrier is marked as unblocked for the currently waiting threads.
3. The number of arrivers in barrier is reset to 0. Unless the next step disables barrier, this means that any subsequent call to barrier-wait will wait, as if barrier had just been created.
4. If disable-on-unblock is true, barrier-wait then disables barrier. Until it is re-enabled, any other call to barrier-wait will return immediately.
5. All the threads waiting on barrier are woken.
6. The symbol :unblocked is returned.

The possible values of result occur in these circumstances:

See also

barrier
barrier-arriver-count
barrier-block-and-wait
barrier-change-count
barrier-count
barrier-disable
barrier-enable
barrier-name
barrier-pass-through
barrier-unblock
make-barrier
19.7.2 Synchronization barriers