Arguments: stream blocking action
Performs record-oriented operations on
stream. Simple-streams have a record-end slot
that normally has a nil value. When the slot
is set to a numeric value, it is interpreted by the read or write
operation as the location in the buffer of the record-end or
break. device-finish-record
is then called, and the return value is interpreted based on the
action specified and the value of
blocking. action is typically one of
:input, :output, or
:prime-input (see the discussion on
"priming" in the second bulleted paragraph below).
blocking is a boolean which specifies whether
or not the method should block during its
operation, or else return immediately.
The return value is either true, meaning success,
or nil, meaning failure. The interpretation
of the nil return depends on the value
of the blocking argument; if nil, then device-finish-record failed to
complete the requested task. If blocking was
true, then a return of nil means an eof was encountered (if
action was :input or
:prime-input), or an error occurred (if
action was :output).
Allegro CL offers calls to device-finish-record under the following circumstances:
string-output-simple-stream: An
xp-simple-stream is a subclass of string-output-stream, and thus has
character orientation. The pretty printer sets the record-end slot of
the xp-simple-stream to the value of *print-right-margin*. Then, when that many
characters have been output, the device-finish-record
method is called which makes formatting decisions about how and where
the accumulated output will be sent to the base stream. dual-channel-simple-stream
A socket-simple-stream that might do "chunking" sets the
record-end slot to a true value while input
chunking is occurring (output-chunking does not use
record-orientation, but writes chunks out whenever the buffer becomes
full or when force-output or
finish-output is called). A special value indicates a
"priming", and device-finish-record is
called with :prime-input as action just before the
first character is read. This call causes chunking to temporarily be
suspended: bytes are read until the #\return #\linefeed combination,
and the bytes read indicate the chunk length. The record-end slot is
set based on the chunk length. When the chunk length is reached,
device-finish-record is called with
:input action, which reads bytes and expects a
terminating #\return #\linefeed combination. If either of these calls
to device-finish-record
return nil, end-of-file processing is
done. There are no usable methods defined.
See streams.htm for information on the simple-streams implementation in Allegro CL. The older but still supported Gray streams implementation is described in gray-streams.htm.
The documentation is described in introduction.htm and the index is in index.htm.
Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.
Created 2000.10.5.