Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
CopyingStreams

NAME

CopyingStreams - provide seek capability on pure input streams

SYNOPSIS

CONST cannotAllocMemory = 0;
CONST invalidInputStream = 1;
CONST outOfMemory = 2;
CONST posOutOfRange = 3;
CONST errors = 4;
TYPE ErrorCode = SHORTINT; (* cannotAllocMemory..posOutOfRange *)
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errorcode: ErrorCode;
   END;
VAR error: Events.EventType;
VAR errormsg: ARRAY errors OF Events.Message;



PROCEDURE Open(VAR s: Streams.Stream; input: Streams.Stream;
               errors: RelatedEvents.Object) : BOOLEAN;

DESCRIPTION

CopyingStreams offers streams with seek and tell capability on base of pure input streams which do not have these capabilities. This is achieved by copying the input into memory. The length of the stream equals the number of bytes read from the underlying input stream. The stream is extended by reading from the end position but not by seeking beyond the current stream length.

CopyingStreams keeps the whole input in an contiguous and extensible area (see Memory). This implementation is hence very efficient but memory-intensive because memory will be allocated in chunks of the page size. Input streams that are known for their small size are better copied into in-memory streams of Texts or LargeTexts.

Copying streams support SubStreams directly and provide therefore an efficient base for substreams of previous input data (e.g. for command line histories).

Open creates a copying stream on base of input. Note that input must not be used otherwise to avoid gaps in the copy of s. The returned stream is linked with the input stream by Forwarders.

DIAGNOSTICS

Errors may result from the stream implementation of the input stream and the associated memory management. Following errors may be generated by CopyingStreams itself:

cannotAllocMemory: Due to a fatal problem at initialization time, CopyingStreams is in general unable to allocate memory.
invalidInputStream: The input stream which was given to Open does not support the Streams.read capability.
outOfMemory: CopyingStreams is unable to read further from the input stream because the internal copy cannot be extended. The problem may result from lack of virtual memory of the operating system or from a problem of the address space management because the internal copy must be kept contiguous.
posOutOfRange: Seek positions are valid only if they range from 0 to the end of the internal copy. It is not possible to enforce reading from the underlying stream by seeking beyond the current stream length.

BUGS

Because the in-memory copy of the underlying stream is not allocated by the garbage collector, streams of CopyingStreams must be closed explicitly to allow the allocated memory to be reclaimed.

The interface is portable but not the current implementation because portability was traded against efficiency.

Edited by: borchert, last change: 2000/05/27, revision: 1.2, converted to HTML: 2000/05/27