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.
SEE ALSO
- Forwarders
-
support of filter objects
- Memory
-
address space management
- Streams
-
general stream operations
- SubStreams
-
streams representing an interval of another stream
- Texts
-
memory-efficient in-memory streams
(see LargeTexts as well)
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
Oberon ||
Library ||
Module Index ||
Search Engine ||
Definition ||
Module