Scieneer Common Lisp 1.3.9 online documentation

ext:stream-waiting-file-descriptor stream direction[Generic Function]

Return the file descriptor and directions that the stream is waiting on to make further progress in the given direction at the operating system interface. The direction may be either :input, :output, or :io. Two values are returned: the file descriptor number and the wait directions which will be either: nil, :input, :output, or :io.

This function is intended to be called after a non-blocking operation on the stream fails to complete because a read or write to an operating system file descriptor would block. For example, after a call to the functions ext:read-byte-no-hang, ext:read-bytes, ext:write-byte-no-hang, ext:write-bytes, or ext:finish-output-no-hang etc.

The direction should match the direction of the previous operation on the stream, otherwise the result may not be relevant. The :io direction may be implemented to support asynchronous two way communication on a stream and is expected to follow a write and read attempt on the stream. When this function is called with direction :io, the prior read should generally follow a prior write because it is possible that a stream write operation will read further input for the stream.

The returned values are suitable for passing as arguments to the function sys:wait-until-fd-usable to wait before retrying the prior operation.

This function only indicates when progress can be made on the stream at the operating system interface and it is not intended to be used to check if a read or write can complete without blocking and it does not check the lisp stream read or write buffers.

The returned wait direction is not necessarily the same as the requested direction because the stream may have a hidden communication protocol that may require writing to the file descriptor before more user data can be read or reading from the file descriptor before more user data can be written. For example an SSL socket stream.

The returned file descriptor is not necessarily the same for input and output. For example, a two-way-stream may have different file descriptors for input and output. Further, the returned file descriptor may change after further progress is made on the stream.

Note that this is an experimental interface and is not yet thoroughly implemented. Binary file descriptor streams are currently supported, including socket streams, and SSL streams. If you are making use of this interface then please contact Scieneer for more information.