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 whether 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-terminate 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.
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
LispWorks User Guide and Reference Manual - 13 Feb 2015