barrier-wait barrier &key timeout callback pass-through discount-on-abort discount-on-timeout disable-on-unblock => result
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:
barrier-wait
will wait, as if the barrier had just been created.
barrier-wait
then disables the barrier. That means that until it is enabled, any call to
barrier-wait
will return immediately.
:unblocked
.The possible values of result occur in these circumstances:
The current process waited and some other process unblocked the barrier.
The current process unblocked the barrier.
The wait timed out.
Pass through because pass-through was true.
The barrier is disabled.