SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST |
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.
C Exception Exception Object Object RT0
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 | Raised if malformed data is received from the remote side of a conversation. |
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 | +---Exception.Checked | +---IO.Error | +--IO.AccessDenied | |
Inherited Methods | |
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: | |
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: |
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: |
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 | |
Class Summary: FileBusy [Detail] | |
+---Exception.Exception | +---Exception.Checked | +---IO.Error | +--IO.FileBusy | |
Inherited Methods | |
Class Summary: FileExists [Detail] | |
+---Exception.Exception | +---Exception.Checked | +---IO.Error | +--IO.FileExists | |
Inherited Methods | |
Class Summary: FileNotFound [Detail] | |
+---Exception.Exception | +---Exception.Checked | +---IO.Error | +--IO.FileNotFound | |
Inherited Methods | |
Class Summary: FormatError [Detail] | |
+---Exception.Exception | +---Exception.Checked | +---IO.Error | +--IO.FormatError | |
Constructor Summary | |
NewFormatError(STRING): FormatError | |
Inherited Methods | |
Class Summary: InvalidArgument [Detail] | |
+---Exception.Exception | +---Exception.Checked | +---IO.Error | +--IO.InvalidArgument | |
Inherited Methods | |
Class Summary: NotImplemented [Detail] | |
+---Exception.Exception | +---Exception.Checked | +---IO.Error | +--IO.NotImplemented | |
Inherited Methods | |
Class Summary: OutOfRange [Detail] | |
+---Exception.Exception | +---Exception.Checked | +---IO.Error | +--IO.OutOfRange | |
Inherited Methods | |
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 | |
Class Summary: SelectionKey [Detail] | |
+---RT0.Object | +---Object.Object | +--IO.SelectionKey | |
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: From Object.Object: |
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: From Object.Object: |
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 |
PROCEDURE (ch: ByteChannel) Flush() RAISES Error;
Flush all buffers associated with channel ch.
PROCEDURE (ch: ByteChannel) INIT()
Redefines: INIT
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'.
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.
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 |
FIELD readyOps: SET
Method Detail |
PROCEDURE (ch: Channel) Close() RAISES Error;
Cancel all selection keys registered for the channel ch and close the channel.
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.
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'.
PROCEDURE (ch: Channel) INIT()
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.
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.
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.
PROCEDURE (ch: Channel) SetPos(pos: LONGINT) RAISES Error;
Change the channels position to pos.
Class Detail: Error |
Method Detail |
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]
Class Detail: ErrorResponse |
Class Detail: FileBusy |
Class Detail: FileExists |
Class Detail: FileNotFound |
Class Detail: FormatError |
Constructor Detail |
PROCEDURE NewFormatError(msg: STRING): FormatError
Class Detail: InvalidArgument |
Class Detail: NotImplemented |
Class Detail: OutOfRange |
Class Detail: ProtocolError |
Class Detail: SelectionKey |
Field Detail |
FIELD attachment-: Object
FIELD channel-: Channel
FIELD fd-: FileDescriptor
FIELD interestOps-: SET
FIELD nextKey-: SelectionKey
FIELD selector-: Selector
Method Detail |
PROCEDURE (k: SelectionKey) Attach(obj: Object)
Set k.attachment to obj.
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.
PROCEDURE (k: SelectionKey) INIT(fd: FileDescriptor; selector: Selector; channel: Channel; ops: SET; attachment: Object)
PROCEDURE (k: SelectionKey) SetInterestOps(ops: SET)
Set k.interestOps to ops.
Class Detail: Selector |
Field Detail |
FIELD keys-: SelectionKey
A list of selection keys registered for this selector. The keys are linked via SelectionKey.nextKey.
Method Detail |
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.
PROCEDURE (s: Selector) Close()
Cancel all selection keys registered for the selector s and close the selector.
PROCEDURE (s: Selector) INIT()
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.
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.
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.
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 |
TYPE FileDescriptor = int
TYPE [SelectionKeyList] = POINTER TO ARRAY OF SelectionKey
Procedure Detail |
PROCEDURE RaiseFormatError(msg: STRING) RAISES FormatError;
PROCEDURE RaiseNotImplemented() RAISES NotImplemented;
Constant Detail |
CONST opAccept
Used to signal interest in connection requests, or to indicate that there are pending requests.
CONST opConnect
Used to signal interest in completion of a currently pending connection attempt, or to indicate that a pending connect has been completed.
CONST opRead
Used to signal interest in new input data, or to indicate that some input data has become available for processing.
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.