Function

Summary

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

Package

mp

Signature

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

Arguments

barrier

A barrier object.

count

A positive integer.

wait-if-used-p

A generalized boolean.

errorp

A boolean.

timeout

nil or a positive real.

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 object 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 the barrier should be unblocked first. The default value of unblock is nil.

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

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

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 the barrier is equal or bigger than 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

1. When barrier-block-and-wait returns the 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.
2. 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 intention of barrier-block-and-wait. If other processes call functions that manipulate the arriver count or the count (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.
3. With the default keyword values (maybe with 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.
4. The argument 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 will call 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.
5. 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.

See also

barrier-wait
make-barrier
barrier-enable
barrier-disable