The generic Process Wait functions are:
process-wait and
process-wait-with-timeout
process-wait-local and process-wait-local-with-timeout
process-wait-local-with-periodic-checks and process-wait-local-with-timeout-and-periodic-checks.
Note: For brevity we sometimes refer to "the
*-periodic-checks
functions" or "the
*-with-timeout
functions".
All the generic Process Wait functions take
wait-reason
and
wait-function
arguments and potentially also arguments to pass to the
wait-function
. The
*-with-timeout
functions mentioned above also take a
timeout
argument. The
*-periodic-checks
functions also take a
period
argument.
The wait-reason is used only to mark the process as waiting for something for debugging purposes. It does not affect the behavior of the functions.
The generic Process Wait functions "wake up" (that is, they simply return to the caller) either when the timeout passed (if they take a timeout argument), or when the wait function returns true. The three pairs of functions mentioned above differ in the mechanism that calls the wait function.
process-wait and process-wait-with-timeout arrange that the "scheduler" will call the wait function when it runs. The "scheduler" is invoked at various points, in an indeterminate process. The advantage of this is that the programmer does not need to worry too much about when the wait function is going to be called. In non-SMP LispWorks (that is, LispWorks 5.1 and earlier) the programmer does not need to worry at all: when some process sets up something that would make the wait function return true, the waiter process could not run anyway until the setting-up process stopped for some reason (including preemption), by which time the scheduler would have called the wait function if it had not done it before. In SMP LispWorks (that is, LispWorks 6.0 and later), these two processes can run simultaneously, so the delay between the setting up and the scheduling is not necessary. It can be avoided by "poking" the waiting process with process-poke, if the waiting process is known, or by invoking the scheduler by process-allow-scheduling.
Note: All the specific Process Wait functions record that they wait, and the operations that allow them to continue implicitly "poke" the waiting process.
A large disadvantage of process-wait and process-wait-with-timeout is that their
wait-function
is called by the "scheduler" in an indeterminate process. That means that the wait function does not see the dynamic environment of the calling process (including error handlers), and cannot be debugged properly. It is also called often, and so it needs to be reasonably fast and not allocate much. In addition, having to call the wait function adds overhead to the system. Therefore in general, if you can achieve the required effect by using either any of the specific wait functions or a
process-wait-local*
function, you should do that and avoid process-wait and process-wait-with-timeout.
process-wait-local and process-wait-local-with-timeout do not have all the disadvantages listed above, but their wait-function is called only when the process is poked (or at the end of the timeout ). That means that the programmer does need to worry about when they are called. Typically some other process will set up something, and then poke the waiting process to check if it can run.
Note: if the setting up process always knows for sure whether the waiting process can run, then it is normally simpler to use one of the specific Process Wait functions, or maybe even process-stop and process-unstop.
The
*-periodic-checks
functions give a partial solution to the question of calling the wait function, by ensuring there is a maximum period of time between calls. If having a bounded delay where a bound of more than 0.1 second is not a problem, then the
*-periodic-checks
functions are a simple and efficient way to achieve it.
When the delays need to be bounded by a shorter period, either one of the specific Process Wait functions or explicit calls to process-poke need to be used. The latter combined with process-wait-local is the most efficient mechanism, but it does require the programmer to ensure that process-poke is called in all the right places.