Waits on a barrier until enough threads arrive.
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 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:
barrier-wait will wait, as if barrier had just been created.barrier-wait then disables barrier. Until it is re-enabled, any other call to barrier-wait will return immediately.:unblocked is returned.The possible values of result occur in these circumstances:
The current process waited and some other process unblocked barrier.
The current process unblocked barrier.
The wait timed out.
The current process did not wait because pass-through is true.
barrier is disabled.
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
Synchronization barriers
LispWorks User Guide and Reference Manual - 20 Sep 2017