IO/C/Stream

This proposal defines a 'Stream' class suitable for use in async and sync programs.

Preamble

Stream objects represent flows of data that pass data elements between an endpoint known as a source or sink and a consumer or producer. Streams may be half or full duplex and may be stacked where intermediate streams are be used as filters or data mutators. Example endpoints are the File, Socket, and Http classes. The TextStream is an example of a filter stream. Streams may buffer the incoming data or not. Streams will issue events to registered listeners for topics of interest. Streams may be used in both synchronous and asynchronous programs.

The Stream interface is an interface for concrete classes. Stream classes will typically augment the Stream class with extra user-facing methods and functionality.

Interface api

function Stream(stream: Stream = null)

Creates a new stream instance. If another stream is provided as an argument to the constructor, the new stream instance will be stacked upon it. Reads and writes from the stream will be relayed to the connected stream and so-on along the stream chain.

function addListener(name: [String | Array], listener: Function): void

Add a listener for events on the stream. Events are issued for important state changes on the stream. Events are issued in both sync and async modes if listeners are registered.

name Name can be a string event name or it can be an array of event names.

listener Callback function to be invoked when the event is emitted.

function get async(): Boolean

Test if the stream is operating in async mode. In async mode, read, write and close methods will not block.

Returns True if the stream is in async mode, otherwise false.

function set async(enable: Boolean): void

Set the streams operating mode. Used to put the stream into async or sync mode.

enable Set to true to put the stream into async mode. Set to false to put the stream into sync mode

function close(): void

Close the stream.

Events The close event is issued when closing the stream.

function read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number

Read data from the stream. If data is available, the call will return immediately with data. If no data is available and the stream is in sync mode, the call will block until data is available. If no data is available and the stream is in async mode, the call will not block and will return immediately. A "readable" event will be issued if data becomes available for reading.

buffer Destination byte array for read data.

offset Integer offset in the byte array to place the data. If the offset is -1, then data is appended to the buffer.

count Integer count of the number of bytes to read. Read up to this number of bytes. If -1, read as much as the buffer will hold up. If the stream is of fixed and known length (such as a file) and the buffer is of sufficient size or is growable, read the entire stream.

Returns an integer count of the bytes actually read. Returns null on eof.

Events The readable event may be listened to be notified when new read data becomes available.

function removeListener(name: [String | Array], listener: Function): void

Remoe a listener from the stream.

name Name can be a string event name or it can be an array of event names.

listener Callback function specified when the listener was previously added.

function write(...data): Number

Write data to the stream. If the stream can accept all the write data, the call returns immediately with the number of elements written. If writing more data than the stream can absorb in sync mode, the call will block until the data is written. If writing more data than the stream can absorb in async mode, the call will not block and will return immediately. A "writable" event will be issued when all the data has been written.

data Variable number of data objects to write. It is stream specific how the written data will be converted or encoded.

Returns an integer count of the bytes actually written. Returns null on a write error.

Events The writable event is issued when the stream becomes empty and it is ready to be written to.