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:

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
    RT0
 
Class List
AccessDenied
ByteChannelCommon base type of channels supporting the ByteChannel.Read and ByteChannel.Write methods.
ChannelA channel is a means by which a program can perform I/O operations.
ErrorBase class of all I/O exceptions raised by channel implementations.
ErrorResponseRaised if the remote side of a conversation sends a reply with an error status code.
FileBusy
FileExists
FileNotFound
FormatError
InvalidArgument
NotImplemented
OutOfRange
ProtocolErrorRaised if malformed data is received from the remote side of a conversation.
SelectionKeyAssociation between a Channel and Selector.
SelectorA mechanism to discover channels that are ready for I/O operations.
Class Summary: AccessDenied [Detail]
  +---Exception.Exception
       |
       +---Exception.Checked
            |
            +---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

Method Summary
Flush()

          Flush all buffers associated with channel ch.
INIT()

          
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, INIT, 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

          
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.
INIT()

          
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
       |
       +---Exception.Checked
            |
            +--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
       |
       +---Exception.Checked
            |
            +---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
       |
       +---Exception.Checked
            |
            +---IO.Error
                 |
                 +--IO.FileBusy
Inherited Methods

From Exception.Exception:

          GetMessage, Name, WriteBacktrace

From IO.Error:

          INIT

 
Class Summary: FileExists [Detail]
  +---Exception.Exception
       |
       +---Exception.Checked
            |
            +---IO.Error
                 |
                 +--IO.FileExists
Inherited Methods

From Exception.Exception:

          GetMessage, Name, WriteBacktrace

From IO.Error:

          INIT

 
Class Summary: FileNotFound [Detail]
  +---Exception.Exception
       |
       +---Exception.Checked
            |
            +---IO.Error
                 |
                 +--IO.FileNotFound
Inherited Methods

From Exception.Exception:

          GetMessage, Name, WriteBacktrace

From IO.Error:

          INIT

 
Class Summary: FormatError [Detail]
  +---Exception.Exception
       |
       +---Exception.Checked
            |
            +---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
       |
       +---Exception.Checked
            |
            +---IO.Error
                 |
                 +--IO.InvalidArgument
Inherited Methods

From Exception.Exception:

          GetMessage, Name, WriteBacktrace

From IO.Error:

          INIT

 
Class Summary: NotImplemented [Detail]
  +---Exception.Exception
       |
       +---Exception.Checked
            |
            +---IO.Error
                 |
                 +--IO.NotImplemented
Inherited Methods

From Exception.Exception:

          GetMessage, Name, WriteBacktrace

From IO.Error:

          INIT

 
Class Summary: OutOfRange [Detail]
  +---Exception.Exception
       |
       +---Exception.Checked
            |
            +---IO.Error
                 |
                 +--IO.OutOfRange
Inherited Methods

From Exception.Exception:

          GetMessage, Name, WriteBacktrace

From IO.Error:

          INIT

 
Class Summary: ProtocolError [Detail]
  +---Exception.Exception
       |
       +---Exception.Checked
            |
            +---IO.Error
                 |
                 +--IO.ProtocolError

Raised if malformed data is received from the remote side of a conversation. This is not used for responses that indicate failure to process a request. An example for a protocol error is an NNTP response message that does not begin with a three digit status code. After such an error, the connection should be closed immediately.

Inherited Methods

From Exception.Exception:

          GetMessage, Name, WriteBacktrace

From IO.Error:

          INIT

 
Class Summary: SelectionKey [Detail]
  +---RT0.Object
       |
       +---Object.Object
            |
            +--IO.SelectionKey

Association between a Channel and Selector.

Field Summary
attachment-: Object

          
channel-: Channel

          
fd-: FileDescriptor

          
interestOps-: SET

          
nextKey-: SelectionKey

          
selector-: Selector

          
Method Summary
Attach(Object)

          Set k.attachment to obj.
Cancel()

          Mark key k as canceled.
INIT(FileDescriptor, Selector, Channel, SET, Object)

          
SetInterestOps(SET)

          Set k.interestOps to ops.
Inherited Methods

From RT0.Object:

          Finalize

From Object.Object:

          Equals, HashCode, ToString

 
Class Summary: Selector [Detail]
  +---RT0.Object
       |
       +---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.
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.
INIT()

          
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 RT0.Object:

          Finalize

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
Method Detail

Flush

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

Flush all buffers associated with channel ch.


INIT

PROCEDURE (ch: ByteChannel) INIT()

Redefines: INIT


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
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'.


INIT

PROCEDURE (ch: Channel) INIT()

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, 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
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.


INIT

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

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.

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.


INIT

PROCEDURE (s: Selector) INIT()

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.