wait-for-input-available

$Revision: 5.0.2.4 $

Function

Package: MULTIPROCESSING

Arguments: (streams &key wait-function whostate timeout)

This lower-level function extends the capabilities of mp:process-wait and mp:process-wait-with-timeout to allow a process to wait for input from multiple streams and to wait for input from a file.

The streams argument may be a single element or a list of elements. Each element may be a stream object or a "file descriptor'' obtained from the operating system (typically a small non-negative integer).

This function waits for input to become available on any of the streams, and when that happens a list of streams/fds (some subset of the given streams argument) that have input available is returned. Here have input available means a subsequent call to read-char or read-byte will immediately return without blocking. (It might return end-of-file status, however).

The default value for the wait-function keyword argument is #'excl:stream-listen. This generic function has methods defined both for integer file descriptors and for terminal, socket, or other "interactive'' streams. When applied to a file stream, it will return t immediately. This function may be applied to streams that do not have a corresponding file descriptor, such as a window-stream (in Common Windows on Unix).

While waiting, the current process's whostate is set to the value specified for the whostate keyword argument, defaulting to "waiting for input", as if a mp:process-wait or mp:process-wait-with-timeout were being called. If a value is specified for the timeout keyword argument and no stream has input available before the timeout occurs, nil is returned. The value of the timeout argument (if it is specified) should be a non-negative real number. The units are seconds. Note that a value less than the granularity of the system will timeout immediately.

Note: This function is intended to replace most calls to the undocumented internal functions mp::watchfor and mp::unwatchfor.

See the discussion under the headings Waiting for input to a file and mp:process-wait vs mp:wait-for-input-available in multiprocessing.htm for information on why to use this function when waiting for input from a file.

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

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