wait-for-input-available

Function

Package: mp

ToC

DocOverview

CGDoc

RelNotes

FAQ

Index

PermutedIndex

Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version

wait-for-input-available

Arguments: stream-or-fds &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 stream-or-fds 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 stream-or-fds argument) that have input available is returned. Here have input available means (when the default wait-function is used) that a subsequent call to read-char or read-byte will immediately return without blocking. (It might return end-of-file status, however).

The wait-function argument should be a function that accepts one argument. If a single stream-or-fd is passed as the stream-or-fds argument, then the wait function will be called with that stream-or-fd. If a list of stream-or-fds is supplied to wait-for-input-available then the wait function will be called on each of those stream-or-fds in turn until it returns non-nil. If the wait function returns nil when applied to every one of the stream-or-fds on the first pass, then this process goes into a wait, with enough information handy to let us do an appropriate select-equivalent OS call when there are no processes ready to run.

The default value for the wait-function keyword argument is #'stream-listen. This generic function has methods defined both for integer file descriptors and for terminal, socket, or other "interactive'' streams. 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).

If you supply your own wait-function, it must determine whether input is available for there is no additional test made by wait-for-input-available beyond the value returned by the wait function.

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 process-wait or 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.

See the discussion in the following sections in multiprocessing.htm for information on why to use this function rather than process-wait when waiting for input from a file. Note that the :os-threads and non :os-threads versions are discussed in different sections.

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