Module Interface Channel

SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST

# Channel

The module defines the abstract data types Channel, Reader, and Writer for stream I/O.

Note 0: All types and procedures declared in this module have to be considered abstract, i.e., they are never instanciated or called. The provided procedure bodies are nothing but hints how a specific channel could start implementing them.

Note 1: A module implementing specific channels (e.g., files, or TCP streams) will provide the procedures

>     PROCEDURE New* (...): Channel;

and (optionally)

>     PROCEDURE Old* (...): Channel.

For channels that correspond to a piece of data that can be both read and changed, the first procedure will create a new channel for the given data location, deleting all data previously contained in it. The latter will open a channel to the existing data.

For channels representing a unidirectional byte stream (like output to / input from terminal, or a TCP stream), only a procedure ``New`' is provided. It will create a connection with the designated location.

The formal parameters of these procedures will include some kind of reference to the data being opened (for example, a file name) and, optionally, flags that modify the way the channel is opened (for example read-only, write-only, etc). Their interface therefore depends on the channel and is not part of this specification.

Note 2: A channel implementation should state how many channels can be open simultaneously. It's common for the OS to support just so many open files or so many open sockets at the same time. Since this value isn't a constant, it's only required to give a statement on the number of open connections for the best case, and which factors can lower this number.

Note 3: A number of record fields in ``Channel`', ``Reader`', and ``Writer`' are exported with write permissions. This is done to permit specializations of the classes to change these fields. The user should consider them read-only.

Note: The list of error codes defined in this module only covers the most typical errors. A specific channel implementation (like Files) will define its own list own codes, containing aliases for the codes below (when appropriate) plus error codes of its own. Every module will provide an error context (an instance of Msg.Context) to translate any code into a human readable message.

### Import List

        Msg
        Time

Class List
Channel |
ErrorContext | This record is exported, so that extensions of Channel can access the error descriptions by extending ErrorContextDesc.
Reader |
Writer |

Class Summary: Channel [Detail]
      +--Channel.Channel
Field Summary
open: BOOLEAN Channel status.
readable: BOOLEAN TRUE iff readers can be attached to this channel with Channel.NewReader.
res: Result Error flag signalling failure of a call to Channel.NewReader, Channel.NewWriter, Channel.Flush, or Channel.Close.
writable: BOOLEAN TRUE iff writers can be attached to this channel with Channel.NewWriter.
Method Summary
ClearError() Sets the result flag ch.res to done.
Close() Flushes all buffers associated with ch, closes the channel, and frees all system resources allocated to it.
Flush() Flushes all buffers related to this channel.
GetModTime(VAR TimeStamp) Retrieves the modification time of the data accessed by the given channel.
Length(): LONGINT Result is the number of bytes of data that this channel refers to.
NewReader(): Reader Attaches a new reader to the channel ch.
NewWriter(): Writer Attaches a new writer to the channel ch.

Class Summary: ErrorContext [Detail]
      +---Msg.Context
           |
           +--Channel.ErrorContext
This record is exported, so that extensions of Channel can access the error descriptions by extending ErrorContextDesc.
Inherited Fields
From Msg.Context: id
Method Summary
GetTemplate(Msg, VAR LString) Translates this module's error codes into strings.
Inherited Methods
From Msg.Context: GetTemplate

Class Summary: Reader [Detail]
      +--Channel.Reader
Field Summary
base: Channel This field refers to the channel the Reader is connected to.
bytesRead: LONGINT Set by Reader.ReadByte and Reader.ReadBytes to indicate the number of bytes that were successfully read.
positionable: BOOLEAN TRUE iff the Reader can be moved to another position with Reader.SetPos; for channels that can only be read sequentially, like input from keyboard, this is FALSE.
res: Result Error flag signalling failure of a call to Reader.ReadByte, Reader.ReadBytes, or Reader.SetPos.
Method Summary
Available(): LONGINT Returns the number of bytes available for the next reading operation.
ClearError() Sets the result flag r.res to done, re-enabling further read operations on r.
Pos(): LONGINT Returns the current reading position associated with the reader r in channel r.base, i.e.
ReadByte(VAR BYTE) Reads a single byte from the channel r.base at the reading position associated with r and places it in x.
ReadBytes(VAR ARRAY OF BYTE, LONGINT, LONGINT) Reads n bytes from the channel r.base at the reading position associated with r and places them in x, starting at index start.
SetPos(LONGINT) Sets the reading position to newPos.

Class Summary: Writer [Detail]
      +--Channel.Writer
Field Summary
base: Channel This field refers to the channel the Writer is connected to.
bytesWritten: LONGINT Set by Writer.WriteByte and Writer.WriteBytes to indicate the number of bytes that were successfully written.
positionable: BOOLEAN TRUE iff the Writer can be moved to another position with Writer.SetPos.
res: Result Error flag signalling failure of a call to Writer.WriteByte, Writer.WriteBytes, or Writer.SetPos.
Method Summary
ClearError() Sets the result flag w.res to done, re-enabling further write operations on w.
Pos(): LONGINT Returns the current writing position associated with the writer w in channel w.base, i.e.
SetPos(LONGINT) Sets the writing position to newPos.
WriteByte(BYTE) Writes a single byte x to the channel w.base at the writing position associated with w.
WriteBytes(ARRAY OF BYTE, LONGINT, LONGINT) Writes n bytes from x, starting at position start, to the channel w.base at the writing position associated with w.

Type Summary
Result = Msg

Constant Summary
channelClosed Set if the rider's channel has been closed, preventing any further read or write operations; this means you called Channel.Close (in which case you made a programming error), or the process at the other end of the channel closed the connection (examples for this are pipes, FIFOs, tcp streams).
closeError Set if closing the channel failed for some reason.
done A ``res`' value of done means successful completion of the last I/O operation.
freeErrorCode Specific channel implemenatations can start defining their own additional error codes for Channel.res, Reader.res, and Writer.res here.
invalidChannel The channel channel isn't valid, e.g.
invalidFormat Set by an interpreting Reader (e.g., TextRiders.Reader) if the byte stream at the current reading position doesn't represent an object of the requested type.
noLength Result value of Channel.Length if the queried channel has no fixed length (for example, if it models input from keybord, or output to terminal).
noModTime Set if no modification time is available for the given channel.
noPosition Result value of Reader.Pos or Writer.Pos if the queried rider has no concept of an indexed reading or writing position, respectively.
noReadAccess Set if Channel.NewReader was called to create a reader on a channel that doesn't allow reading access.
noRoom Set if a write operation failed because there isn't any space left on the device, e.g.
noTmpName Creation of a temporary file failed because the system was unable to assign an unique name to it.
noWriteAccess Set if Channel.NewWriter was called to create a reader on a channel that doesn't allow reading access
outOfRange Set if ``SetPos`' has been called with a negative argument or it has been called on a rider that doesn't support positioning.
readAfterEnd Set if a call to Reader.ReadByte or Reader.ReadBytes tries to access a byte beyond the end of the file (resp.
readError Unspecified read error.
writeError A write error occured; usually this error happens with a writer, but for buffered channels this may also occur during a Channel.Flush or a Channel.Close.

Class Detail: Channel

Field Detail

### open

    FIELD open: BOOLEAN

> Channel status. Set to TRUE on channel creation, set to FALSE by calling Channel.Close. Closing a channel prevents all further read or write operations on it.

### readable

    FIELD readable: BOOLEAN

> TRUE iff readers can be attached to this channel with Channel.NewReader.

### res

    FIELD res: Result

> Error flag signalling failure of a call to Channel.NewReader, Channel.NewWriter, Channel.Flush, or Channel.Close. Initialized to done when creating the channel. Every operation sets this to done on success, or to a message object to indicate the error source.

### writable

    FIELD writable: BOOLEAN

> TRUE iff writers can be attached to this channel with Channel.NewWriter.

Method Detail

### ClearError

    PROCEDURE (ch: Channel) ClearError()

> Sets the result flag ch.res to done.

### Close

    PROCEDURE (ch: Channel) Close()

> Flushes all buffers associated with ch, closes the channel, and frees all system resources allocated to it. This invalidates all riders attached to ch, and they can't be used further. On success, i.e. if all read and write operations (including flush) completed successfully, ch.res is set to done. An opened channel can only be closed once, successive calls of Channel.Close are undefined. Note that unlike the Oberon System all opened channels have to be closed explicitly. Otherwise resources allocated to them will remain blocked.

### Flush

    PROCEDURE (ch: Channel) Flush()

> Flushes all buffers related to this channel. Any pending write operations are passed to the underlying OS and all buffers are marked as invalid. The next read operation will get its data directly from the channel instead of the buffer. If a writing error occurs during flushing, the field ch.res will be changed to writeError, otherwise it's assigned done. Note that you have to check the channel's Channel.res flag after an explicit flush yourself, since none of the attached writers will notice any write error in this case.

### GetModTime

    PROCEDURE (ch: Channel) GetModTime(VAR mtime: TimeStamp)

> Retrieves the modification time of the data accessed by the given channel. If no such information is avaiblable, ch.res is set to noModTime, otherwise to done.

### Length

    PROCEDURE (ch: Channel) Length(): LONGINT

> Result is the number of bytes of data that this channel refers to. If ch represents a file, then this value is the file's size. If ch has no fixed length (e.g. because it's interactive), the result is noLength.

### NewReader

    PROCEDURE (ch: Channel) NewReader(): Reader

> Attaches a new reader to the channel ch. It is placed at the very start of the channel, and its Reader.res field is initialized to done. ch.res is set to done on success and the new reader is returned. Otherwise result is NIL and ch.res is changed to indicate the error cause. Note that always the same reader is returned if the channel does not support multiple reading positions.

### NewWriter

    PROCEDURE (ch: Channel) NewWriter(): Writer

> Attaches a new writer to the channel ch. It is placed at the very start of the channel, and its Writer.res field is initialized to done. ch.res is set to done on success and the new writer is returned. Otherwise result is NIL and ch.res is changed to indicate the error cause. Note that always the same reader is returned if the channel does not support multiple writing positions.

Class Detail: ErrorContext

Method Detail

### GetTemplate

    PROCEDURE (context: ErrorContext) GetTemplate(msg: Msg;
                          VAR templ: LString)

> Translates this module's error codes into strings. The string usually contains a short error description, possibly followed by some attributes to provide additional information for the problem.

> The method should not be called directly by the user. It is invoked by ``res.GetText()`' or ``res.GetLText`'.

> Redefines: GetTemplate

Class Detail: Reader

Field Detail

### base

    FIELD base: Channel

> This field refers to the channel the Reader is connected to.

### bytesRead

    FIELD bytesRead: LONGINT

> Set by Reader.ReadByte and Reader.ReadBytes to indicate the number of bytes that were successfully read.

### positionable

    FIELD positionable: BOOLEAN

> TRUE iff the Reader can be moved to another position with Reader.SetPos; for channels that can only be read sequentially, like input from keyboard, this is FALSE.

### res

    FIELD res: Result

> Error flag signalling failure of a call to Reader.ReadByte, Reader.ReadBytes, or Reader.SetPos. Initialized to done when creating a Reader or by calling Reader.ClearError. The first failed reading (or Reader.SetPos) operation changes this to indicate the error, all further calls to Reader.ReadByte, Reader.ReadBytes, or Reader.SetPos will be ignored until Reader.ClearError resets this flag. This means that the successful completion of an arbitrary complex sequence of read operations can be ensured by asserting that res equals done beforehand and also after the last operation.

Method Detail

### Available

    PROCEDURE (r: Reader) Available(): LONGINT

> Returns the number of bytes available for the next reading operation. For a file this is the length of the channel r.base minus the current reading position, for an sequential channel (or a channel designed to handle slow transfer rates) this is the number of bytes that can be accessed without additional waiting. The result is ``-1`' if Channel.Close was called for the channel, or no more byte are available and the remote end of the channel has been closed. Note that the number of bytes returned is always a lower approximation of the number that could be read at once; for some channels or systems it might be as low as ``1`' even if tons of bytes are waiting to be processed.

### ClearError

    PROCEDURE (r: Reader) ClearError()

> Sets the result flag r.res to done, re-enabling further read operations on r.

### Pos

    PROCEDURE (r: Reader) Pos(): LONGINT

> Returns the current reading position associated with the reader r in channel r.base, i.e. the index of the first byte that is read by the next call to Reader.ReadByte resp. Reader.ReadBytes. This procedure will return noPosition if the reader has no concept of a reading position (e.g. if it corresponds to input from keyboard), otherwise the result is not negative.

### ReadByte

    PROCEDURE (r: Reader) ReadByte(VAR x: BYTE)

> Reads a single byte from the channel r.base at the reading position associated with r and places it in x. The reading position is moved forward by one byte on success, otherwise r.res is changed to indicate the error cause. Calling this procedure with the reader r placed at the end (or beyond the end) of the channel will set r.res to readAfterEnd. r.bytesRead will be ``1`' on success and ``0`' on failure. Calls to this procedure while ``r.res # done`' will be ignored.

### ReadBytes

    PROCEDURE (r: Reader) ReadBytes(VAR x: ARRAY OF BYTE;
                        start: LONGINT;
                        n: LONGINT)

> Reads n bytes from the channel r.base at the reading position associated with r and places them in x, starting at index start. The reading position is moved forward by n bytes on success, otherwise r.res is changed to indicate the error cause. Calling this procedure with the reader r placed less than n bytes before the end of the channel will will set r.res to readAfterEnd. r.bytesRead will hold the number of bytes that were actually read (being equal to n on success). Calls to this procedure while ``r.res # done`' will be ignored.

> Pre-condition: ``(n >= 0) & (0 <= start) & (start+n <= LEN (x))`'

### SetPos

    PROCEDURE (r: Reader) SetPos(newPos: LONGINT)

> Sets the reading position to newPos. A negative value of newPos or calling this procedure for a reader that doesn't allow positioning will set r.res to outOfRange. A value larger than the channel's length is legal, but the following read operation will most likely fail with an readAfterEnd error unless the channel has grown beyond this position in the meantime. Calls to this procedure while ``r.res # done`' will be ignored, in particular a call with ``r.res.code = readAfterEnd`' error will not reset Reader.res to done.

Class Detail: Writer

Field Detail

### base

    FIELD base: Channel

> This field refers to the channel the Writer is connected to.

### bytesWritten

    FIELD bytesWritten: LONGINT

> Set by Writer.WriteByte and Writer.WriteBytes to indicate the number of bytes that were successfully written.

### positionable

    FIELD positionable: BOOLEAN

> TRUE iff the Writer can be moved to another position with Writer.SetPos. for channels that can only be written sequentially, like output to terminal, this is FALSE.

### res

    FIELD res: Result

> Error flag signalling failure of a call to Writer.WriteByte, Writer.WriteBytes, or Writer.SetPos. Initialized to done when creating a Writer or by calling Writer.ClearError. The first failed writing (or ``SetPos`') operation changes this to indicate the error, all further calls to Writer.WriteByte, Writer.WriteBytes, or Writer.SetPos will be ignored until Writer.ClearError resets this flag. This means that the successful completion of an arbitrary complex sequence of write operations can be ensured by asserting that res equals done beforehand and also after the last operation. Note that due to buffering a write error may occur when flushing or closing the underlying file, so you have to check the channel's res field after any Channel.Flush or the final Channel.Close, too.

Method Detail

### ClearError

    PROCEDURE (w: Writer) ClearError()

> Sets the result flag w.res to done, re-enabling further write operations on w.

### Pos

    PROCEDURE (w: Writer) Pos(): LONGINT

> Returns the current writing position associated with the writer w in channel w.base, i.e. the index of the first byte that is written by the next call to Writer.WriteByte or Writer.WriteBytes. This procedure will return noPosition if the writer has no concept of a writing position (e.g. if it corresponds to output to terminal), otherwise the result is not negative.

### SetPos

    PROCEDURE (w: Writer) SetPos(newPos: LONGINT)

> Sets the writing position to newPos. A negative value of newPos or calling this procedure for a writer that doesn't allow positioning will set `w.res' to outOfRange. A value larger than the channel's length is legal, the following write operation will fill the gap between the end of the channel and this position with zero bytes. Calls to this procedure while ``w.res # done`' will be ignored.

### WriteByte

    PROCEDURE (w: Writer) WriteByte(x: BYTE)

> Writes a single byte x to the channel w.base at the writing position associated with w. The writing position is moved forward by one byte on success, otherwise w.res is changed to indicate the error cause. w.bytesWritten will be ``1`' on success and ``0`' on failure. Calls to this procedure while ``w.res # done`' will be ignored.

### WriteBytes

    PROCEDURE (w: Writer) WriteBytes(x: ARRAY OF BYTE;
                         start: LONGINT;
                         n: LONGINT)

> Writes n bytes from x, starting at position start, to the channel w.base at the writing position associated with w. The writing position is moved forward by n bytes on success, otherwise w.res is changed to indicate the error cause. w.bytesWritten will hold the number of bytes that were actually written (being equal to n on success). Calls to this procedure while ``w.res # done`' will be ignored.

> Pre-condition: ``(n >= 0) & (0 <= start) & (start+n <= LEN (x))`'

Type Detail

### Result

    TYPE Result = Msg

Constant Detail

### channelClosed

    CONST channelClosed

> Set if the rider's channel has been closed, preventing any further read or write operations; this means you called Channel.Close (in which case you made a programming error), or the process at the other end of the channel closed the connection (examples for this are pipes, FIFOs, tcp streams).

### closeError

    CONST closeError

> Set if closing the channel failed for some reason.

### done

    CONST done

> A ``res`' value of done means successful completion of the last I/O operation.

### freeErrorCode

    CONST freeErrorCode

> Specific channel implemenatations can start defining their own additional error codes for Channel.res, Reader.res, and Writer.res here.

### invalidChannel

    CONST invalidChannel

> The channel channel isn't valid, e.g. because it wasn't opened in the first place or was corrupted somehow; for a rider this refers to the channel in the ``base`' field.

### invalidFormat

    CONST invalidFormat

> Set by an interpreting Reader (e.g., TextRiders.Reader) if the byte stream at the current reading position doesn't represent an object of the requested type.

### noLength

    CONST noLength

> Result value of Channel.Length if the queried channel has no fixed length (for example, if it models input from keybord, or output to terminal).

### noModTime

    CONST noModTime

> Set if no modification time is available for the given channel.

### noPosition

    CONST noPosition

> Result value of Reader.Pos or Writer.Pos if the queried rider has no concept of an indexed reading or writing position, respectively. For example, this is the case, if it models input from keybord, or output to terminal.

### noReadAccess

    CONST noReadAccess

> Set if Channel.NewReader was called to create a reader on a channel that doesn't allow reading access.

### noRoom

    CONST noRoom

> Set if a write operation failed because there isn't any space left on the device, e.g. if the disk is full or you exeeded your quota. Usually this error happens with a writer, but for buffered channels this may also occur during a Channel.Flush or a Channel.Close.

### noTmpName

    CONST noTmpName

> Creation of a temporary file failed because the system was unable to assign an unique name to it. Closing or registering an existing temporary file beforehand might help.

### noWriteAccess

    CONST noWriteAccess

> Set if Channel.NewWriter was called to create a reader on a channel that doesn't allow reading access

### outOfRange

    CONST outOfRange

> Set if ``SetPos`' has been called with a negative argument or it has been called on a rider that doesn't support positioning.

### readAfterEnd

    CONST readAfterEnd

> Set if a call to Reader.ReadByte or Reader.ReadBytes tries to access a byte beyond the end of the file (resp. channel). This means that there weren't enough bytes left or the read operation started at (or after) the end.

### readError

    CONST readError

> Unspecified read error.

### writeError

    CONST writeError

> A write error occured; usually this error happens with a writer, but for buffered channels this may also occur during a Channel.Flush or a Channel.Close.