device-finish-record

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.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.