process-join

Arguments: process &key (errorp t) error-values (search-list (quote (:current :previous :next)))

Suspend the current process until mp:process-thread of process exits, and then return the list of result values of the preset function of process. If the thread does not exit normally, signal a mp::process-join-error if errorp is true or return error-values if errorp is nil.

This simple state of affairs is complicated by the fact that a process can have several threads associated with it over its lifetime. One may want (1) to wait for the current thread or (2) get the return values of the most recently finished thread of process or (3) wait for the thread to finish even if there is no current one. The search-list argument controls which threads are considered and in what order. Valid elements for search-list are :current, :previous, and :next. The list is processed in order. :next, if present, should always be last in the list.

If :current is found and there is a live thread associated with the process then it is waited for and its values returned as described above, else the processing of the list continues. If :previous is found and there was a thread associated with process but by now it has finished then its values are returned (no waiting is needed in this case), else the processing of the list continues. If :next is found then process-join waits for a thread of process to finish.

The difference between :current and :next is that :next will wait for a thread that has not even started while :current only waits if there is a live thread.

If the end of the search-list list is reached, that is considered an error and a mp::process-join-error is signaled if errorp is true, and error-values is returned if errorp is nil.

When successful, process-join returns a second value: the element of search-list which resulted in matching a thread and terminating the processing of the list.

This function is async unwind safe: one can wrap it in sys:with-timeout.

Example:

(mp:process-join process :search-list '(:current :previous :next))

:CURRENT makes it wait for the current thread associated with the
process if any.

:PREVIOUS makes it take the return values from the most recently
finished thread that was associated with the process if any.

:NEXT (there hasn't been a thread associated with this process) so we
wait for the next one.

The first of these to succeed ends the call to PROCESS-JOIN and
returns the associated values. :NEXT, if present, should be last.  If,
for example, :SEARCH-LIST is '(:current :previous) and there is no
current thread and was no previous thread, an error is signaled, as in
this case:

cg-user(11):   (let ((process (mp:make-process)))
    (mp:process-join process :search-list '(:current :previous)))
Error: Joining process #<process Process.1> failed.

[condition type: process-join-error]
cg-user(12): 

Because the process created in the LET binding was never started,
there is no current thread for it and no previous thread. Since
:SEARCH-LIST is '(:current :previous), an error is signaled.

See multiprocessing.htm for general information on multiprocessing in Allegro CL.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page is new in the 9.0 release.
Created 2019.8.20.