reap-os-subprocess

$Revision: 5.0.2.6 $

Function

Package: SYSTEM

Arguments: (&key pid wait)

This function replaced sys:os-wait, which has the same functionality. This function has a better interface (using keyword rather than optional arguments).

If a process is started by the excl:run-shell-command with the wait keyword argument to that function nil, then the process will remain in the system after it completes until either Lisp exits or Lisp executes sys:reap-os-subprocess to inquire about the exit status. To prevent the system becoming clogged with processes, a program that spawns a number of processes with :wait nil must be sure to call sys:reap-os-subprocess after each process finishes.

Exactly what sys:reap-os-subprocess does depends on the status of spawned processes and the keyword arguments. The pid argument controls what processes might be considered on by sys:reap-os-subprocess. If pid is -1 (the default), all processes are considered. If pid is 0, only processes in the same process group (as the executing Lisp image) are considered. If pid is a positive integer, only the process with that process id is considered. In the rest of this description, processes means `processes considered by sys:reap-os-subprocess'. See the Unix documentation of the waitpid() system call.

If there are any processes started by excl:run-shell-command with the argument :wait nil which have exited but for which sys:reap-os-subprocess has not been run, one of them is selected by the operating system and its status and process id are returned in that order as multiple values.

If there are no such processes which have exited but there are processes which are still running, then the behavior of sys:reap-os-subprocess depends on the wait keyword argument. If it is t (the default), sys:reap-os-subprocess will wait (disabling multiprocessing, if necessary) until one of the running processes exits. Then that process's status and id are returned. If wait is nil, sys:reap-os-subprocess will immediately return two values: nil and nil if there are no processes to clean up; a status and a pid if the process with number pid is cleaned up, nil and the pid argument to sys:reap-os-subprocess if processes are still running and none has yet exited.

If there are no running processes, sys:reap-os-subprocess returns immediately with the values nil, nil.

This function simply calls the Unix function waitpid with the pid and nohang flags. Its behavior is determined by the behavior of that function.

See os_interface.htm for information on running shell programs.

The general documentation description is in introduction.htm. The index is in index.htm.