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). If stream-or-fds is nil, this function returns nil immediately.

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. If any does not return nil, the rest are also checked and a list of all that did not return nil is returned. On any pass, if every one of the stream-or-fds gets us a nil return, 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.

• Waiting for input from a stream
• mp:process-wait vs mp:wait-for-input-available

See also process-wait and waiting-for-input-available.

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 was not revised from the 9.0 page.
Created 2015.5.21.