barrier-block-and-wait

barrier-block-and-wait Function

Summary

Enables a barrier, waits until a specified number of arrivers arrive, and then wakes immediately.

Package

Signature

barrier-block-and-wait barrier count &key wait-if-used-p errorp timeout unblock => result

Arguments

`barrier`⇩	A barrier.
`count`⇩	A positive integer.
`wait-if-used-p`⇩	A generalized boolean.
`errorp`⇩	A boolean.
`timeout`⇩	A non-negative real or `nil`.
`unblock`⇩	A boolean.

Values

result⇩

An integer, a symbol or a mp:process object.

Description

The function barrier-block-and-wait enables the barrier barrier with t, that is it makes any number of arrivers wait, and then waits until count arrivers arrive.

wait-if-used-p controls whether to wait if another process is already inside barrier-block-and-wait. The default value of wait-if-used-p is nil.

barrier is a barrier made by make-barrier.

errorp controls whether to signal an error if another process is already inside barrier-block-and-wait and wait-if-used-p is nil. The default value of errorp is nil.

timeout, if non-nil, specifies the time in seconds to wait before timing out. The default value of timeout is nil.

unblock specifies whether processes that already wait on barrier should be unblocked first. The default value of unblock is nil.

barrier-block-and-wait is "using" barrier, and only one process can do this the same time. barrier-block-and-wait first tries to mark barrier as used by the current process, which will fail if another process is inside barrier-block-and-wait with the same barrier. In this case it does one of three options:

If wait-if-used-p is non-nil, it calls barrier-wait on barrier (without any keyword argument) and returns the result.
If errorp is non-nil, it calls error.
Otherwise is returns the other process.

Once barrier-block-and-wait has successfully marked barrier as used, it changes its count to t as if by calling (barrier-change-count barrier t), which will cause other barrier-wait calls to wait. If unblock is non-nil, it first unblocks all processes that wait on the barrier, so the effect is the same as (barrier-enable barrier t).

It then waits until the arriver count of barrier is greater than or equal to count, or, if timeout is supplied, timeout seconds passed. It then returns the number of arrivers.

result can be one of three types:

integer	The call was successful, and `result` is the number of arrivers.
symbol	`barrier` was in use, and `wait-if-used-p` is non-nil, so barrier-wait was called. `result` is the result of barrier-wait.
`mp:process`	`barrier` is in use, and `result` is the process that uses it.

Notes

When barrier-block-and-wait returns. barrier is still set with t, that is calls to barrier-wait on barrier will wait. Normally the current process will go on to do some operations that require the other processes to wait, and then release them by calling barrier-disable or barrier-enable.
In typical usage, the arriver count is just increased by one by each call to barrier-wait, so as long as other processes use only barrier-wait (or barrier-block-and-wait with wait-if-used-p non-nil), barrier-block-and-wait will return after count processes called barrier-wait and are waiting. That is the intended purpose of barrier-block-and-wait. If other processes call functions that manipulate the arriver count or the count of barrier (barrier-disable, barrier-enable, barrier-unblock, barrier-change-count), then barrier-block-and-wait will "get confused", in the sense that while its behavior is still well-defined, it is not intuitive.
With the default keyword values (not counting timeout), barrier-block-and-wait is useful for controlling a fixed set of processes by another "master" process. The processes in the set need to call barrier-wait at appropriate points. When the "master" process wants to stop them for a while, it calls barrier-block-and-wait. When it wants to restart them, it calls barrier-disable.
A non-nil value of wait-if-used-p is useful when any member of a group of processes may decide that it needs to stop all the other processes in the group. In this case, this process calls barrier-block-and-wait with wait-if-used-p non-nil (and count the number of processes in the group minus one). If two of the processes happen to call it at the same time, one will get the barrier, and the other process will have to wait.
The effect of barrier-block-and-wait can be approximated by using barrier-change-count followed by normal process-wait that checks the arrivers count in the wait function. barrier-block-and-wait has two advantages:
(a) It checks against more than one process trying to do it at the same time.

(b) barrier-block-and-wait will wake up immediately when the arriver count reaches the right number. process-wait will wake up only when the scheduler checks the wait function and wakes it up.