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

barrier

A barrier.

timeout

A non-negative number.

pass-through

A boolean.

discount-on-abort

A boolean.

discount-on-timeout

A boolean.

disable-on-unblock

A boolean.

callback

A function designator.

Values

result

t , nil or one of the keywords :unblocked , :passed-through and :timeout .

Description

The function barrier-wait waits on a barrier until enough threads arrive. 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, it does not actually wait.

discount-on-abort controls whether to change the arrivers count on an abort.

discount-on-timeout controls whether to change the arrivers count on a timeout.

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

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

barrier-wait first checks if the barrier is disabled, and if it is barrier-wait returns nil immediately. It then checks the number of arrivers, 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, and then waits for the barrier to be unblocked (unless pass-through is true). If the number of arrivers is the count minus 1, barrier-wait unblocks the barrier (described below) and returns :unblocked .

discount-on-abort , discount-on-timeout , disable-on-unblock and callback allow you to control the waiting and also the unblocking of the barrier. 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 the 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 , meaning no timeout. 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 after a timeout barrier-wait decrements the arrivers count, so the call has no overall effect on the arrivers count.

If barrier-wait is aborted while it waits (for example by process-kill or throwing using process-interrupt), by default it does not change the arrivers count, 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 on aborting barrier-wait decrements the arrivers count, 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 the barrier: when the number of arrivers is the count of the barrier minus 1, barrier-wait "unblocks the barrier". This involves the following steps:

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

The possible values of result occur in these circumstances:

t

The current process waited and some other process unblocked the barrier.

:unblocked

The current process unblocked the barrier.

:timeout

The wait timed out.

:passed-through

Pass through because pass-through was true.

nil

The barrier is disabled.

See also

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