21.5. Non-Blocking Input and Output
Prev | Chapter 21. Streams | Next

## 21.5. Non-Blocking Input and Output

In addition to the standard functions `LISTEN` and `READ-CHAR-NO-HANG`, CLISP provides the following functionality facilitating non-blocking input and output, both binary and character.

`(`EXT:READ-CHAR-WILL-HANG-P` `stream`)`

  `EXT:READ-CHAR-WILL-HANG-P` queries the stream's input status. It returns `NIL` if `READ-CHAR` and `PEEK-CHAR` with a `peek-type` of `NIL` will return immediately. Otherwise it returns `T`. (In the latter case the standard `LISTEN` function would return `NIL`.)

  Note the difference with `(`NOT` (`LISTEN` `stream`))`: When the `end-of-stream` is reached, `LISTEN` returns `NIL`, whereas `EXT:READ-CHAR-WILL-HANG-P` returns `NIL`.

  Note also that `EXT:READ-CHAR-WILL-HANG-P` is not a good way to test for `end-of-stream`: If `EXT:READ-CHAR-WILL-HANG-P` returns `T`, this does not mean that the `stream` will deliver more characters. It only means that it is not known at this moment whether the `stream` is already at `end-of-stream`, or will deliver more characters.

`(`EXT:READ-BYTE-LOOKAHEAD` `stream`)`
  To be called only if `stream`'s `STREAM-ELEMENT-TYPE` is `(`UNSIGNED-BYTE` 8)` or `(`SIGNED-BYTE` 8)`. Returns `T` if `READ-BYTE` would return immediately with an `INTEGER` result. Returns `:EOF` if the `end-of-stream` is already known to be reached. If `READ-BYTE`'s value is not available immediately, returns `NIL` instead of waiting.
`(`EXT:READ-BYTE-WILL-HANG-P` `stream`)`
  To be called only if `stream`'s `STREAM-ELEMENT-TYPE` is `(`UNSIGNED-BYTE` 8)` or `(`SIGNED-BYTE` 8)`. Returns `NIL` if `READ-BYTE` will return immediately. Otherwise it returns true.
`(`EXT:READ-BYTE-NO-HANG` `stream` `&OPTIONAL` `eof-error-p` `eof-value`)`
  To be called only if `stream`'s `STREAM-ELEMENT-TYPE` is `(`UNSIGNED-BYTE` 8)` or `(`SIGNED-BYTE` 8)`. Returns an `INTEGER` or does `end-of-stream` handling, like `READ-BYTE`, if that would return immediately. If `READ-BYTE`'s value is not available immediately, returns `NIL` instead of waiting.

### `LISTEN` on binary streams

The [ANSI CL standard] specification for `LISTEN` mentions “character availability” as the criterion that determines the return value. Since a `CHARACTER` is never available on a binary `STREAM` (i.e., a stream with `STREAM-ELEMENT-TYPE` being a subtype of `INTEGER`), `LISTEN` returns `NIL` for such streams. (You can use `SOCKET:SOCKET-STATUS` to check binary streams). Any other behavior would be hard to make consistent: consider a bivalent stream, i.e., a `STREAM` that can be operated upon by both `READ-CHAR` and `READ-BYTE`. What should `LISTEN` return on such a stream if what is actually available on the stream at the moment is only a part of a multi-byte character? Right now one can use first `SOCKET:SOCKET-STATUS` to check if anything at all is available and then use `LISTEN` to make sure that a full `CHARACTER` is actually there.

| These notes document CLISP version 2.45 | Last modified: 2008-05-14

Enter your search termsSubmit search form
Webclisp.cons.orgclisp.podval.orgwww.lisp.org

Prev | Up | Next
21.4. Bulk Input and Output | Home | 21.6. Newline Convention