process-poke

process-poke Function

Summary

Makes a waiting process call its wait function.

Package

Signature

process-poke process => result

Arguments

process⇩

A process.

Values

result

A boolean.

Description

If the process process is waiting, the function process-poke causes it to run its wait-function as soon as possible, and if the wait function returns true, the process returns from the waiting function.

process-poke is especially useful when using the process-wait-local-* functions. With process-wait-local and process-wait-local-with-timeout, it is the only way to ensure that the waiting process checks the wait function. The other functions also check periodically, but process-poke is still useful to make them wake up immediately.

With a non-local wait function (that is, in process-wait and process-wait-with-timeout), process-poke is useful in SMP LispWorks to ensure that the process wakes and checks its wait-function immediately. process-poke has no effect on non-SMP LispWorks for process-wait and process-wait-with-timeout.

You can also use process-poke to wake up a process that waits using current-process-pause.

process-poke returns t if it actually poked the process or nil otherwise (when the process is not waiting or is stopped).

The process wait functions are designed to call the wait-function just before going to sleep, in a way that guards against a race condition between process-poke and the waiting function. In particular, they ensure that if a process goes to wait with a wait-function that checks some value, and another process sets this value and calls process-poke on the first process, the first either will check the value before going to sleep, or wake up and check the value. The first process is never going to get stuck because it went to sleep just as the other process set the value. Note that this is guaranteed only when the value is set before process-poke is called.

Functions that cause specific wait functions to be ready to run (for example mailbox-send which causes mailbox-read to be ready to run) implicitly pokes a process that waits, so there is no need to use process-poke when these functions are used.

Examples

Worker process function:

(defun worker-process-function (work-struct)
  (loop (mp:process-wait-local "Waiting for request"
                               'worker-struct-request
                               work-struct)
        (process-request
         (worker-struct-request work-struct))
        (setf (worker-struct-request work-struct) nil)))

Another process distributes requests:

(dolist (work-struct *work-structs*)
  (unless (worker-struct-request work-struct)
    (setf (worker-struct-request work-struct) request)
    (mp:process-poke
     (worker-struct-process work-struct))
    (return work-struct)))

This specific example can be implemented a little more simply by mailbox-read and mailbox-send, but if the wait function needs to check for something else it can be easily added.