Function

Summary

Run forms when a given process terminates.

Package

mp

Signature

ensure-process-cleanup cleanup-form &key priority force process =>

Signature

ensure-process-cleanup cleanup-form &optional process =>

Arguments

cleanup-form

Form to run when process terminates.

priority

An integer in the inclusive range [-1000000, 1000000].

force

A boolean.

process

A mp:process object.

Values

None.

Description

The function ensure-process-cleanup ensures that the cleanup-form is present for the process process. When process terminates, its cleanup forms are run. Cleanup forms can be functions of one argument (the process), or lists, in which case the cl:car is applied to the process and the cl:cdr of the list.

process is the process to watch for termination. By default, this is the value returned by get-current-process.

priority determines the execution order of the forms. Higher priority means later execution. The system uses values between 700000 and 900000 for cleanups that need to be last, and 0 for other cleanups. The default value of priority is 0.

force determines what to do if the same cleanup is already registered but with a different priority. When adding cleanup forms, ensure-process-cleanup uses cl:equal to ensure that the form is only added once. If a cleanup already exists with the same priority, ensure-process-cleanup just returns nil, otherwise it acts according to force: if force is nil it invokes an error, but if force is t then ensure-process-cleanup removes the old entry before adding the new entry. The default value of force is nil.

When ensure-processes-cleanup is called on a foreign thread, that is a thread that was not created by LispWorks, the cleanups are executed after the outermost foreign-callable returns and before return to the foreign code that called it (that is when no Lisp frames remain on the stack).

Compatibility note

Before LispWorks 7.1, the cleanups where never executed when ensure-processes-cleanup was called in a foreign thread.

Notes

1. You can test for whether the current process is executing its cleanups with current-process-in-cleanup-p.
2. For compatibility wth LispWorks 6.1 and earlier versions, ensure-process-cleanup can also be called like this:
(ensure-process-cleanup cleanup-form process)

Such calls are still allowed, for backwards compatibility, however please update your programs to call it like this:

(ensure-process-cleanup cleanup-form

                        :priority priority

                        :force force

                        :process process
)

Example

A process calls add-process-dependent each time a dependent object is added to a process. When the process terminates, inform-dependent-of-dead-process is called on all dependent objects.

(defun add-process-dependent (dependent)

  (mp:ensure-process-cleanup

      `(delete-process-dependent ,dependent)))

(defun delete-process-dependent (process dependent)

  (inform-dependent-of-dead-process dependent process))

See also

current-process-in-cleanup-p
process-terminate