current-process-pause Function

Summary

Sleeps for a specified time, but can be woken up.

Package

mp

Signature

current-process-pause time &optional function &rest args => result

Arguments

time⇩	A positive number.
function⇩	A function designator.
args⇩	Arguments passed to function.

Values

result

A Lisp object.

Description

The function current-process-pause sleeps for time seconds, but wakes up if another process did something to wake up the current process (normally this is process-poke, but it can also be process-interrupt, process-stop, process-unstop or process-kill).

current-process-pause is quite similar to cl:sleep, but it returns if anything causes the process to wake up, even if the time did not pass.

If function is passed just before going to sleep, current-process-pause applies function to args, and if this returns a true value current-process-pause returns it immediately. function and args are not used otherwise. If another process calls process-poke on the current process after setting something that causes function to return true, it guarantees that current-process-pause will return immediately without sleeping.

If another process woke up the current process, current-process-pause returns the keyword :poked. If it slept the full time, it returns nil.

Notes

1. In contrast to process-wait, the argument function to current-process-pause is applied only once, and within the dynamic scope of current-process-pause. It therefore does not have any of the restrictions that the wait-function of process-wait has.
2. The purpose of function is to guard against the possibility that another process pokes the current process while it is in the process of going to sleep.
3. There is no way to distinguish between the function returning :poked and the process being poked in some way.
4. The pausing does not happen reliably, and it can return :poked in a situation when it seems unexpected. For example, if the current process does:

   (mailbox-read *mailbox*)
   ...
   (current-process-pause)
   

   the call to current-process-pause may return poked, because a process that sent an event to the mailbox tried to poke the current process, and by the time this poke happened the current process is already inside current-process-pause. The only guarantees are that current-process-pause does not wait when a poke occurred, and that it returns nil only when it paused the full time.

Examples

Supposed you want to have a process that each minute does some cleanup, but may also be told by other processes to go and do the cleanup. The process be doing:

(loop
  (mp:current-process-pause 60 'check-for-need-cleanup)
  (do-cleanup))

Another process which wants to provoke a cleanup will do:

(setup-cleanup-flag)
 
(mp:process-poke *cleanup-process*)

Note that check-for-need-cleanup is passed to current-process-pause, because another process may call process-poke after current-process-pause was called but before it went to sleep. If check-for-need-cleanup was not passed, current-process-pause would unnecessarily sleep the whole 60 seconds in this case. The same thing could be implemented by process-wait-with-timeout, but the implementation above does not require a wait function that can run in another dynamic scope repeatedly at arbitrary times, and it uses much less system resources. It is also easier to debug.

See also

process-poke