process-wait-local Function

Summary

Has the same semantics as process-wait, but does not interact with the scheduler.

Package

mp

Signature

process-wait-local wait-reason function &rest args => t

Arguments

Description

The function process-wait-local suspends the current Lisp process until the predicate function applied to args returns true.

process-wait-local has same semantics as process-wait, but is "local", which here means that it does not interact with the scheduler. The scheduler does not call the wait function and hence never wakes the waiting process.

The wait function function is called only by the calling process, before going to sleep, and whenever it is "poked". A process is typically "poked" by calling process-poke, but all the other process managing functions (process-unstop, process-interrupt, process-terminate) also "poke" the process. Returning from any of the generic Process Waiting functions (see 19.6.2 Generic Process Wait functions) or cl:sleep also implicitly pokes the process. A process may be also poked internally.

Because the wait function is checked only when the process is poked, it is the responsibility of the application to poke the process when it should check the wait function. This is the disadvantage of process-wait-local and process-wait-local-with-timeout.

wait-reason is used as the wait-reason while waiting.

Note: See process-wait-local-with-periodic-checks and process-wait-local-with-timeout-and-periodic-checks for functions that periodically check the wait functions.

One advantage of using the "local" waiters is that the wait function is called only by the waiting process. This means that the wait function does not have any of the restrictions that the wait function of process-wait has. In particular:

1. It does not matter if the wait function is not very fast. Note however, that it may be called several times, and not always in a predictable way, so it is better not to make it too slow or allocate much. You also cannot rely on any side effect that is cumulative inside the wait function, except in the call that returns true (because this happens at most once).
2. If there is an unhandled error in the wait function it enters the debugger like normal Lisp code, so it is easier to debug.
3. The wait function is in the dynamic scope of the calling process, and so it sees all the dynamic bindings and can throw to all the catchers. That also means that all the handlers and restarts of the calling process are applicable in the wait function.
4. The wait function can itself call Process Waiting functions or cl:sleep, with a small caveat: since these functions may implicitly "poke" the process, if the wait function calls any of them and then returns false, it may be immediately called again (if it returns true then process-wait-local itself returns). Normally this is not a problem, because it is still waiting, but it does mean that the wait function is called more times than expected.
5. The wait function, because it can call Process Waiting functions, can use locks without causing errors. Note, however, that if the lock is held, it will cause an internal call to a Process Waiting function, which will "poke" the process and hence cause another call of the wait function (unless it returns true).
6. The wait function is visible in the output of the profiler.

Another advantage of the "local" functions is that they do not interact with the scheduler and so they reduce the overhead of the scheduler.

process-wait-local always returns t.

See also

process-poke
process-wait-local-with-periodic-checks
process-wait-local-with-timeout
19.6 Process Waiting and communication between processes