buffered-stream Class

Summary

A stream class giving access to stream buffers.

Package

stream

Superclasses

fundamental-stream

Subclasses

lob-stream
string-stream
socket-stream

Initargs

Description

The class buffered-stream provides default methods for the majority of the functions in the User Defined Streams protocol. The default methods implement buffered I/O, requiring the user to define only the methods stream-read-buffer, stream-write-buffer and stream-element-type for each subclass of buffered-stream. You are at liberty to redefine other methods in subclasses as long as they obey the rules outlined here. For example it is usually desirable to implement methods on stream-listen, stream-check-eof-no-hang and close as well.

The initargs are handled by the method (method initialize-instance :after (buffered-stream)) as follows:

Input and/or output buffers are created based on the value direction. There is no default value, and you must supply a value.

element-type determines the stream-element-type of the stream. The default is base-char. For binary streams, use base-char.

static-buffers controls whether the buffers for input and output are allocated as static objects (see 11.3.2.1 Allocation of static objects). The default is nil, which causes these buffers are allocated as ordinary Lisp objects that may be moved by the garbage collector. If static-buffers is non-nil, then the buffers are made as static Lisp objects. Most importantly, that allows you to pass the buffers directly to foreign functions, and that is typically the reason for supplying static-buffers. Note: The static buffers are allocated from a resource, and are released when the stream is closed, so foreign code should not access them after that.

All the methods in the User Defined Streams protocol are defined for buffered-stream as follows:

• The methods on stream-read-char, stream-read-line, stream-read-sequence, stream-unread-char, stream-read-char-no-hang, stream-clear-input handle input from the buffer. They each call stream-fill-buffer to fill the empty buffer as required.
• The methods on stream-write-char, stream-write-string, stream-write-sequence, stream-clear-output, stream-finish-output, stream-force-output and stream-line-column handle output to the buffer. They each call stream-flush-buffer to make the buffer empty as required.
• There are :around methods on stream-listen and close which handle the buffer.
• The methods on input-stream-p, output-stream-p return the appropriate values based on the value of the :direction initarg.
• The open-stream-p method returns true if close has not been called.

Examples

See the extended example in:

(example-edit-file "streams/buffered-stream")

See also

close
stream-flush-buffer
stream-fill-buffer
stream-listen
stream-read-buffer
stream-write-buffer
with-stream-input-buffer