Streams

The aim of the stream design presented here is an open architecture for programming with streams, which should be applicable when the interface to some object can be characterized by either serial access to, or delivery of, objects.

The two specific objectives are: (i) transfer of objects between a process and disk storage; (ii) transfer of objects between one process and another.

The fundamental purpose of a stream object in the scheme presented here is to provide an interface between two objects through the two functions read, for streams from which objects are received, and write, for streams to which objects are sent.

Stream classes


<stream> : class
This is the root of the stream class hierarchy and also defines the basic stream class.

Initialization options

read-action : <function>
A function which is called by the <stream> generic-read method. The accessor for this slot is called stream-read-action.
write-action : <function>
A function which is called by the <stream> generic-write method. The accessor for this slot is called stream-write-action.
The following accessor functions are defined for <stream>
stream-lock
A lock, to be used to allow exclusive access to a stream.
stream-source
An object to which the stream is connected and from which input is read.
stream-sink
An object to which the stream is connected and to which ouptut is written.
stream-buffer
An object which is used to buffer data by some subclasses of <stream>. Its default value is ().
stream-buffer-size
The maximum number of objects that can be stored in stream-buffer. Its default value is 0.
The transaction unit of <stream> is <object>.


streamp : function

Arguments

object
Returns object, if it is a stream, otherwise ().


from-stream : function
A constructor function of one argument for <stream> which returns a stream whose stream-read-action is the given argument.


to-stream : function
A constructor function of one argument for <stream> which returns a stream whose stream-write-action is the given argument.


<buffered- stream> : class
This class specializes <stream> by the use of a buffer which may grow arbitrarily large. The transaction unit of <buffered-stream> is <object>.


<fixed- buffered-stream> : class
This class specializes <buffered-stream> by placing a bound on the growth of the buffer. The transaction unit of <fixed-buffere-stream> is <object>.


<file- stream> : class
This class specializes <fixed-buffered-stream> by providing an interface to data stored in files on disk. The transaction unit of <file-stream> is <character>. The following additional accessor functions are defined for <file-stream>
file-stream-filename
The path identifying the file system object associated with the stream.
file-stream-mode
The mode of the connection between the stream and the file system object (usually either read or write).
file-stream-buffer-position
A key identifying the current position in the stream's buffer.

Stream operators


connect : function

Arguments

source
The source object from which the stream will read data.
sink
The sink object to which the stream will write data.
[options]
An optional argument for specifying implementation-defined options.
Connects source to sink according to the class-specific behaviours of generic-connect.


generic-connect : generic-function
This is a function of three arguments: source, sink and options as described for connect.


generic-connect : method

Specialized arguments

(source <stream>)
The stream which is to be the source of sink
(sink <stream>)
The stream which is to be the sink of source.
(options <list>)
A list of implementation-defined options.
Connects the source of sink to source and the sink of source to sink. The return value is ().


generic-connect : method

Specialized arguments

(source <path>)
A path name.
(sink <file-stream>)
The stream via which data will be received from the file named by path.
(options <list>)
A list of implementation-defined options
Opens the object identified by the path source for reading and connects sink to it. Hereafter, sink may be used for reading data from sink, until sink is disconnected or reconnected. Implementation-defined options for the opening of files may be specified using the third argument. See also open-input-file.


generic-connect : method

Specialized arguments

(source <file-stream>)
The stream via which data will be sent to the file named by path.
(sink <path>)
A path name.
(options <list>)
A list of implementation-defined options
Opens the object identifed by the path sink for writing and connects source to it. Hereafter, source may be used for writing data to sink, until source is disconnected or reconnected. Implementation-defined options for the opening of files may be specified using the third argument. See also open-output-file.


reconnect : generic-function

Generic arguments

(s1 <stream>)
A stream.
(s2 <stream>)
A stream.
Transfers the source and sink connections of s1 to s2, leaving s1 disconnected.


reconnect : method

Specialized arguments

(s1 <stream>)
A stream.
(s2 <stream>)
A stream.
Implements the reconnect operation for objects of class <stream>.


disconnect : generic-function

Generic arguments

(s <stream>)
A stream.
Disconnects the stream s from its source and/or its sink.


disconnect : method

Specialized arguments

(s <stream>)
A stream.
Implements the diconnect operation for objects of class <stream>.


disconnect : method

Specialized arguments

(s <file-stream>)
A stream.
Implements the diconnect operation for objects of class <file-stream>. In particular, this involves closing the file associated with the stream.

Stream objects


stdin : <file-stream>
The standard input stream, which is a file-stream and whose transaction unit is therefore character. In Posix compliant configurations, this object is initialized from the Posix stdin object. Note that although stdin itself is a constant binding, it may be connected to different files by the reconnect operation.


lispin : <stream>
The standard lisp input stream, and its transaction unit is object. This stream is initially connected to stdin (although not necessarily directly), thus a read operation on lispin will case characters to be read from stdin and construct and return an object corresponding to the next lisp expression. Note that although lispin itself is a constant binding, it may be connected to different source streams by the reconnect operation.


stdout : <file-stream>
The standard output stream, which is a file-stream and whose transaction unit is therefore character. In Posix compliant configurations, this object is initialized from the Posix stdout object. Note that although stdout itself is a constant binding, it may be connected to different files by the reconnect operation.


stderr : <file-stream>
The standard error stream, which is a file-stream and whose transaction unit is therefore character. In Posix compliant configurations, this object is initialized from the Posix stderr object. Note that although stderr itself is a constant binding, it may be connected to different files by the reconnect operation.

Buffer management


fill-buffer : generic-function

Generic arguments

(stream <buffered-stream>)
A stream.
The buffer associated with stream is refilled from its source. This function returns a count of the number of items read. This function is guaranteed to be called when an attempt is made to read from a buffered stream whose buffer is either empty, or from which all the items have been read.


fill-buffer : method

Specialized arguments

(stream <buffered-stream>)
A stream.


fill-buffer : method

Specialized arguments

(stream <file-stream>)
A stream.


flush-buffer : generic-function

Generic arguments

(s <buffered-stream>)
A stream.
The contents of the buffer associated with stream is flushed to its sink. If this operation succeeds, a true value is returned, otherwise the result is (). This function is guaranteed to be called when an attempt is made to write to a buffered stream whose buffer is full.


flush-buffer : method

Specialized arguments

(stream <buffered-stream>)
A stream.
Implements the flush-buffer operation for objects of class <buffered-stream>.


flush-buffer : method

Specialized arguments

(stream <file-stream>)
A stream.
Implements the flush-buffer operation for objects of class <file-stream>. This method is called both when the buffer is full and after a newline character is written to the buffer.


<end-of- stream> : <stream-condition>
Signalled when end-of-stream is called when encountering the end of the stream.

See also:

generic-read


end-of-stream : generic-function

Generic arguments

(stream <stream>)
A stream.
This function is guaranteed to be called when a read operation encounters the end of the stream and the eos-error-p argument to read has a non-() value.


end-of-stream : method

Specialized arguments

(stream <buffered-stream>)
A stream.
Signals the end of stream condition.


end-of-stream : method

Specialized arguments

(stream <file-stream>)
A stream.
Disconnects stream and signals the end of stream condition.

Reading from streams


read : function

Arguments

[stream]
A stream.
[eos-error-p]
A boolean.
[eos-value]
Value to be returned to indicate end of stream.
The argument stream defaults to lispin, eos-error-p defaults to ()and eos-value defaults to eos-default-value. The result is that of calling generic-read with the arguments supplied or defaulted as described.


generic-read : generic-function

Generic arguments

(stream <stream>)
A stream.
(eos-error-p <object>)
A boolean.
(eos-value <object>)
Value to be returned to indicate end of stream.
The next transaction unit from stream is returned as the result. If the end of stream is encountered and the value of eos-error-p is (), the result is eos-value. If the end of stream is encountered and the value of eos-error-p is non-(), the function end-of-stream is called with the argument stream.


generic-read : method

Specialized arguments

(stream <stream>)
A stream.
(eos-error-p <object>)
A boolean.
(eos-value <object>)
Value to be returned to indicate end of stream.
Implements the generic-read operation for objects of class <stream>. The result is that of calling the read-action of stream with the arguments stream, eos-error-p and eos-value.


generic-read : method

Specialized arguments

(stream <buffered-stream>)
A buffered stream.
(eos-error-p <object>)
A boolean.
(eos-value <object>)
Value to be returned to indicate end of stream.
Implements the generic-read operation for objects of class <buffered-stream>. The result is the next object stored in the stream buffer. If the buffer is empty, the function fill-buffer is called. If the refilling operation did not succeed, the end of stream action is carried out as described under the generic-function generic-read.


generic-read : method

Specialized arguments

(stream <file-stream>)
A file stream.
(eos-error-p <object>)
A boolean.
(eos-value <object>)
Value to be returned to indicate end of stream.
Implements the generic-read operation for objects of class <file-stream>. The result is the next character stored in the stream buffer. If the buffer is empty, the function fill-buffer is called. If the refilling operation did not succeed, the end of stream action is carried out as described under the generic-function generic-read.

Writing to streams


write : function

Arguments

obj
Object to be written.
[stream]
Stream for writing.


generic-write : generic-function
generic

Generic arguments

(obj <object>)
Object to be written.
(stream <stream>)
Stream for writing.


generic-write : method

Specialized arguments

(obj <object>)
Object to be written.
(stream <stream>)
Stream for writing.


generic-write : method

Specialized arguments

(obj <object>)
Object to be written.
(stream <buffered-stream>)
Stream for writing.


generic-write : method

Specialized arguments

(obj <object>)
Object to be written.
(stream <file-stream>)
Stream for writing.

Additional functions


read-line : function

Arguments

stream
A stream.
[eos-error-p]
A boolean.
eos-value
Value to be returned to indicate end of stream.


prin : function

Arguments

obj
Object to be written.
[stream]
Stream for writing.


print : function

Arguments

obj
Object to be written.
[stream]
Stream for writing.


flush : function

Arguments

[stream]
Stream for writing.


newline : function

Arguments

[stream]
Stream for writing.


prin-char : function

Arguments

char
Character to be written.
[stream]
Stream for writing.
[times]
Integer count.
Outputs char on stream. The stream defaults to stdout. The count times defaults to 1. If times is specified, then stream must also be specified.


sread : function

Arguments

stream
A stream.
[eos-error-p]
A boolean.
eos-value
Value to be returned to indicate end of stream.


sprin : function

Arguments

obj
Object to be written.
[stream]
Stream for writing.

Convenience forms


open-input-file : function

Arguments

path
A path identifying a file system object.
Allocates and returns a new <file-stream> object whose source is connected to the file system object identified by path.


open-output-file : function

Arguments

path
A path identifying a file system object.
Allocates and returns a new <file-stream> object whose sink is connected to the file system object identified by path.


with-input-file : macro
with-input-file = '(', 'with-input-file', path, {form}, ')';


with-output-file : macro


with-source : macro


with-sink : macro

Posix bindings


fopen : function

Arguments

stream
A stream to connect to a file.
path
A path identifying a file system object.
mode
How the file is to be opened.
Connects stream to the file system object identified by path according to the specified mode. The mode is specified by one of the following symbols:
r
Opens file for reading.
w
Opens file for writing, creating the file if it does not exist.
a
Opens file for append output, creating the file if it does not exist. If the file exists, the stream position points to the end of the file, so any output adds to the file.
r+
Opens the file for update. Both input and output can be performed on the stream. Any existing data in the file is preserved.
w+
Opens the file for update. Both input and output can be performed on the stream. Any existing data in the file is eliminated; the file is re-created if it exists.
a+
Opens the file for update. The file can be read at any location, but any output to the file occurs starting from its current end.
The result is stream.


fclose : function

Arguments

stream
A stream.
Closes the file stream stream and returns (). The stream is disconnected from the file system object with which it was associated and may no longer be used for read or write operations. The stream buffer is flushed to the file system before the file is closed.


fcntl : function

Arguments

stream
A stream.
[cmds]
fcntl commands as defined below.
This function returns or sets information about an open file stream. The symbol command determines the action of fcntl and in some cases, the third argument command-values must also be supplied. The command can be any one of the following symbols, which are a subset of those defined in 1990:??? (POSIX C API):
F_GETFL
This is the default value. In this case, fcntl returns a list of symbols or integers, in no particular order, describing the stream's attributes. These values can be among the following:
O_APPEND
The file is open in append mode.
O_NONBLOCK
Waiting for data does not cause blocking.
O_RDONLY
The file is open for read only.
O_RDWR
The file is open for read and write.
O_WRONLY
The file is open for write only.
Other implementation-defined values specified as integers.
F_SETFL
In this case the the third argument command-values must be a list of attributes from the set described above for F_GETFL. However, according to 1990:???, only the values O_APPEND and O_NONBLOCK can be modified.

Discussion

If you would like to read the discussion about this document and its development please click here. If you would like to add to the discussion please click here.
Julian Padget, jap@maths.bath.ac.uk, this version December 21, 1994