Module Interface IO

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

# IO

This set of modules defines a set of input/output abstractions for files, sockets, pipes, and so on. The modules are not related to the library modules Channel, Files, and derivates. Their goals are quite different:

- Provide an thin and efficient layer on top of the operation system's I/O features.

- Use exceptions to propagate errors to the application that are reported by the C library.

- Provide an abstraction for I/O multiplexing that allows to use different mechanisms besides select().

- The level of abstraction should be high-level enough to care for slighty different I/O primitives, most notably under Windows.

The roots of the interface are partially the Java IO package, Python, and the Oberon-2 standard I/O modules. Eventually, the modules will replace the ``IO:*`' inherited from the old ``libxml`' package.

### Import List

        C
        Exception
        Exception
        Object
        Object

Class List
AccessDenied |
ByteChannel | Common base type of channels supporting the ByteChannel.Read and ByteChannel.Write methods.
Channel | A channel is a means by which a program can perform I/O operations.
Error | Base class of all I/O exceptions raised by channel implementations.
ErrorResponse | Raised if the remote side of a conversation sends a reply with an error status code.
FileBusy |
FileExists |
FileNotFound |
FormatError |
InvalidArgument |
NotImplemented |
OutOfRange |
ProtocolError |
SelectionKey | Association between a Channel and Selector.
Selector | A mechanism to discover channels that are ready for I/O operations.

Class Summary: AccessDenied [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.AccessDenied
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: ByteChannel [Detail]
      +---IO.Channel
           |
           +--IO.ByteChannel
Common base type of channels supporting the ByteChannel.Read and ByteChannel.Write methods.
Inherited Fields
From IO.Channel: readyOps
Constructor Summary
InitByteChannel(ByteChannel)
Method Summary
Flush() Flush all buffers associated with channel ch.
Read(VAR ARRAY OF BYTE, LONGINT, LONGINT): LONGINT Read a sequence of bytes from the channel into the buffer.
TransferTo(LONGINT, ByteChannel): LONGINT Transfer upto length bytes from channel ch to target.
Write(ARRAY OF BYTE, LONGINT, LONGINT): LONGINT Write a sequence of bytes to this channel from the buffer.
Inherited Methods
From IO.Channel: Close, CloseAndRegister, FileDescriptor, KeyForSelector, RegisterWithSelector, SetBlocking, SetPos

Class Summary: Channel [Detail]
      +--IO.Channel
A channel is a means by which a program can perform I/O operations. Examples for channels are IO:FileChannel.Channel, IO:SocketChannel.Channel, and IO:SocketChannel.ServerChannel.
Field Summary
readyOps: SET
Constructor Summary
InitChannel(Channel)
Method Summary
Close() Cancel all selection keys registered for the channel ch and close the channel.
CloseAndRegister() Like Channel.Close, but register the channel's target with its naming service once done.
FileDescriptor(): FileDescriptor Return the file descriptor of the channel.
KeyForSelector(Selector): SelectionKey Return selection key of ch for selector sel.
RegisterWithSelector(Selector, SET, Object): SelectionKey Register the channel ch with the selector sel.
SetBlocking(BOOLEAN) Change the channel's blocking mode.
SetPos(LONGINT) Change the channels position to pos.

Class Summary: Error [Detail]
      +---Exception.Exception
           |
           +--IO.Error
Base class of all I/O exceptions raised by channel implementations.
Method Summary
INIT(STRING) Initialize exception e and set msg as its message.
Inherited Methods
From Exception.Exception: GetMessage, INIT, Name, WriteBacktrace

Class Summary: ErrorResponse [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.ErrorResponse
Raised if the remote side of a conversation sends a reply with an error status code.
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: FileBusy [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.FileBusy
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: FileExists [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.FileExists
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: FileNotFound [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.FileNotFound
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: FormatError [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.FormatError
Constructor Summary
NewFormatError(STRING): FormatError
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: InvalidArgument [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.InvalidArgument
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: NotImplemented [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.NotImplemented
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: OutOfRange [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.OutOfRange
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: ProtocolError [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--IO.ProtocolError
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: SelectionKey [Detail]
      +---Object.Object
           |
           +--IO.SelectionKey
Association between a Channel and Selector.
Field Summary
attachment-: Object
channel-: Channel
fd-: FileDescriptor
interestOps-: SET
nextKey-: SelectionKey
selector-: Selector
Constructor Summary
InitSelectionKey(SelectionKey, FileDescriptor, Selector, Channel, SET, Object)
Method Summary
Attach(Object) Set k.attachment to obj.
Cancel() Mark key k as canceled.
SetInterestOps(SET) Set k.interestOps to ops.
Inherited Methods
From Object.Object: Equals, HashCode, ToString

Class Summary: Selector [Detail]
      +---Object.Object
           |
           +--IO.Selector
A mechanism to discover channels that are ready for I/O operations. For example, a selector can be used to find out for which channels input data is available. Note: The definition of this class covers both selectors that report the current state of a channel, and those that only report an event if a channel becomes ready. Selector.Select only adds new ready flags, but never clears them. I/O operations like ByteChannel.Read, ByteChannel.Write, SocketChannel.Channel.Connect, and SocketChannel.ServerChannel.Accept clear the corresponding flag if the channel is in non-blocking mode and they get an ``EWOULDBLOCK`' error from the libc function.
Field Summary
keys-: SelectionKey A list of selection keys registered for this selector.
Constructor Summary
InitSelector(Selector)
Method Summary
AddSelectionKey(FileDescriptor, Channel, SET, Object): SelectionKey Private method of the selector.
Close() Cancel all selection keys registered for the selector s and close the selector.
NextKey(): SelectionKey Return the next selection key of selector s with a non-empty intersection of SelectionKey.interestOps and Channel.readyOps.
RemoveCanceled() Removes all keys that have been marked as "canceled" from the selector.
RemoveSelectionKey(SelectionKey) Private method of the selector.
Select(LONGINT, LONGINT): LONGINT Determine if operations on registered channels are ready.
Inherited Methods
From Object.Object: Equals, HashCode, ToString

Type Summary
FileDescriptor = int
[SelectionKeyList] = POINTER TO ARRAY OF SelectionKey

Procedure Summary
RaiseFormatError(STRING)
RaiseNotImplemented()

Constant Summary
opAccept Used to signal interest in connection requests, or to indicate that there are pending requests.
opConnect Used to signal interest in completion of a currently pending connection attempt, or to indicate that a pending connect has been completed.
opRead Used to signal interest in new input data, or to indicate that some input data has become available for processing.
opWrite Used to signal interest to produce output on a channel, or to indicate that there is room for more data to be passed to the operating system.

Class Detail: AccessDenied

Class Detail: ByteChannel

Constructor Detail

### InitByteChannel

    PROCEDURE InitByteChannel(ch: ByteChannel)

Method Detail

### Flush

    PROCEDURE (ch: ByteChannel) Flush()
      RAISES Error;

> Flush all buffers associated with channel ch.

### Read

    PROCEDURE (ch: ByteChannel) Read(VAR buffer: ARRAY OF BYTE;
                   start: LONGINT;
                   length: LONGINT): LONGINT
      RAISES Error;

> Read a sequence of bytes from the channel into the buffer.

> An attempt is made to read up to length bytes from the channel. The bytes are written to buffer, starting at position start. Result is the number of bytes actually read, or ``-1`' if the read position is at the end of the channel, and length is not zero.

> A read operation might not read length bytes, and in fact it might not read any bytes at all. Whether or not it does so depends upon the nature and state of the channel. A socket channel in non-blocking mode, for example, cannot read any more bytes than are immediately available from the socket's input buffer; similarly, a file channel cannot read any more bytes than remain in the file. It is guaranteed, however, that if a channel is in blocking mode and there is at least one byte remaining in the buffer then this method will block until at least one byte is read.

> Pre-condition: ``0 <= start <= start+length <= LEN(buffer)`' and ``length >= 0`'.

### TransferTo

    PROCEDURE (ch: ByteChannel) TransferTo(length: LONGINT;
                         target: ByteChannel): LONGINT
      RAISES Error;

> Transfer upto length bytes from channel ch to target. Result is the number of bytes actually copied.

### Write

    PROCEDURE (ch: ByteChannel) Write(buffer: ARRAY OF BYTE;
                    start: LONGINT;
                    length: LONGINT): LONGINT
      RAISES Error;

> Write a sequence of bytes to this channel from the buffer.

> An attempt is made to write up to length bytes to the channel. The bytes are taken from buffer, beginning at position start.

> A write operation can return after writing less than length bytes. That is, some types of channels, depending upon their state, may write only some of the bytes or possibly none at all. A socket channel in non-blocking mode, for example, cannot write any more bytes than are free in the socket's output buffer. Result is the number of bytes actually written.

> Pre-condition: ``0 <= start <= start+length <= LEN(buffer)`' and ``length >= 0`'.

Class Detail: Channel

Field Detail

### readyOps

    FIELD readyOps: SET

Constructor Detail

### InitChannel

    PROCEDURE InitChannel(ch: Channel)

Method Detail

### Close

    PROCEDURE (ch: Channel) Close()
      RAISES Error;

> Cancel all selection keys registered for the channel ch and close the channel.

### CloseAndRegister

    PROCEDURE (ch: Channel) CloseAndRegister()
      RAISES Error;

> Like Channel.Close, but register the channel's target with its naming service once done. Right now, only IO:FileChannel supports this feature; see IO:FileChannel.tmpFile for details. By default, this method simply calls Channel.Close.

### FileDescriptor

    PROCEDURE (ch: Channel) FileDescriptor(): FileDescriptor

> Return the file descriptor of the channel. This is the integer number that is used to identify the channel on the level of the C library. If the channel is not associated with a file descriptor, result is ``-1`'.

### KeyForSelector

    PROCEDURE (ch: Channel) KeyForSelector(sel: Selector): SelectionKey

> Return selection key of ch for selector sel. Result is NIL if the channel is not registered with the selector.

### RegisterWithSelector

    PROCEDURE (ch: Channel) RegisterWithSelector(sel: Selector;
                                   ops: SET;
                                   attachment: Object): SelectionKey

> Register the channel ch with the selector sel. If such a registration already exists, then return the old selection key. Otherwise, create a new key with an interest set ops and attachment attachment and return it.

### SetBlocking

    PROCEDURE (ch: Channel) SetBlocking(block: BOOLEAN)
      RAISES Error;

> Change the channel's blocking mode. Channels typically default to blocking mode on creation.

> If a channel does not support non-blocking operation, then any call to this method is ignored. Rider implementations from IO:BinaryRider and IO:TextRider only work with blocking channels.

### SetPos

    PROCEDURE (ch: Channel) SetPos(pos: LONGINT)
      RAISES Error;

> Change the channels position to pos.

Class Detail: Error

Method Detail

### INIT

    PROCEDURE (e: Error) INIT(msg: STRING)

> Initialize exception e and set msg as its message. msg may be NIL, but in this case Exception.GetMessage must be redefined to provide a non-NIL message.

> Pre-condition: e is not NIL.

> [Description inherited from INIT]

> Redefines: INIT

Class Detail: ErrorResponse

Class Detail: FileBusy

Class Detail: FileExists

Class Detail: FileNotFound

Class Detail: FormatError

Constructor Detail

### NewFormatError

    PROCEDURE NewFormatError(msg: STRING): FormatError

Class Detail: InvalidArgument

Class Detail: NotImplemented

Class Detail: OutOfRange

Class Detail: ProtocolError

Class Detail: SelectionKey

Field Detail

### attachment

    FIELD attachment-: Object

### channel

    FIELD channel-: Channel

### fd

    FIELD fd-: FileDescriptor

### interestOps

    FIELD interestOps-: SET

### nextKey

    FIELD nextKey-: SelectionKey

### selector

    FIELD selector-: Selector

Constructor Detail

### InitSelectionKey

    PROCEDURE InitSelectionKey(k: SelectionKey;
                               fd: FileDescriptor;
                               selector: Selector;
                               channel: Channel;
                               ops: SET;
                               attachment: Object)

Method Detail

### Attach

    PROCEDURE (k: SelectionKey) Attach(obj: Object)

> Set k.attachment to obj.

### Cancel

    PROCEDURE (k: SelectionKey) Cancel()

> Mark key k as canceled. The key is immediately eliminated from the channels's list of keys. It is removed from the selector's key list with the next call to Selector.Select. Closing a channel cancels all its selection keys.

### SetInterestOps

    PROCEDURE (k: SelectionKey) SetInterestOps(ops: SET)

> Set k.interestOps to ops.

Class Detail: Selector

Field Detail

### keys

    FIELD keys-: SelectionKey

> A list of selection keys registered for this selector. The keys are linked via SelectionKey.nextKey.

Constructor Detail

### InitSelector

    PROCEDURE InitSelector(s: Selector)

Method Detail

### AddSelectionKey

    PROCEDURE (s: Selector) AddSelectionKey(fd: FileDescriptor;
                              channel: Channel;
                              ops: SET;
                              attachment: Object): SelectionKey

> Private method of the selector. Create and initialize a selection key. The caller is responsible for adding the key to the selector.

### Close

    PROCEDURE (s: Selector) Close()

> Cancel all selection keys registered for the selector s and close the selector.

### NextKey

    PROCEDURE (s: Selector) NextKey(): SelectionKey

> Return the next selection key of selector s with a non-empty intersection of SelectionKey.interestOps and Channel.readyOps. Result is NIL if no such channel exists.

### RemoveCanceled

    PROCEDURE (s: Selector) RemoveCanceled()

> Removes all keys that have been marked as "canceled" from the selector. This is a private method, and should only be called from Selector.Select.

### RemoveSelectionKey

    PROCEDURE (s: Selector) RemoveSelectionKey(k: SelectionKey)

> Private method of the selector. Do any bookkeeping require to eliminate the selection key. The caller is responsible for removing the key from the selector's list of keys.

### Select

    PROCEDURE (s: Selector) Select(sec: LONGINT;
                     usec: LONGINT): LONGINT
      RAISES Error;

> Determine if operations on registered channels are ready. The function returns the number of channels with a non-empty ready set. Result is ``0`' if no channels are ready or have become ready until the time the specified timeout expires. If this function is called with a channel already being ready, then it behaves as if a timeout of zero had been requested.

> After a call to Selector.Select, the method Selector.NextKey iterates over all ready channels.

Type Detail

### FileDescriptor

    TYPE FileDescriptor = int

### SelectionKeyList

    TYPE [SelectionKeyList] = POINTER TO ARRAY OF SelectionKey

Procedure Detail

### RaiseFormatError

    PROCEDURE RaiseFormatError(msg: STRING)
      RAISES FormatError;

### RaiseNotImplemented

    PROCEDURE RaiseNotImplemented()
      RAISES NotImplemented;

Constant Detail

### opAccept

    CONST opAccept

> Used to signal interest in connection requests, or to indicate that there are pending requests.

### opConnect

    CONST opConnect

> Used to signal interest in completion of a currently pending connection attempt, or to indicate that a pending connect has been completed.

### opRead

    CONST opRead

> Used to signal interest in new input data, or to indicate that some input data has become available for processing.

### opWrite

    CONST opWrite

> Used to signal interest to produce output on a channel, or to indicate that there is room for more data to be passed to the operating system.