Stream

Module	ejs
Definition	class Stream
Specified	evolving

Stream objects represent streams of data that pass data elements between an endpoint known as a source or sink and a consumer or producer.

Streams are 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. The data elements passed by streams may be any series of objects including: bytes, lines of text, numbers or objects. Streams may buffer the incoming data or not. Streams may issue events to registered observers for topics of interest. Streams may offer synchronous and asynchronous APIs.

Properties

Qualifiers	Property	Type	Description
static const	BOTH		Both directions constant for flush().
static const	READ		Read direction constant for flush().
static const	WRITE		Write direction constant for flush().
get set	async	Boolean	The current async mode. Set to true if the stream is in async mode.

Stream Class Methods

(No own class methods defined)

Qualifiers	Method

Stream Instance Methods

Qualifiers	Method
	close(): Void
	Close the stream.
	flush(dir: Number = BOTH): Void
	Flush the stream and underlying streams.
	off(name, observer: Function): Void
	Remove an observer from the stream.
	on(name, observer: Function): Stream
	Add an observer to the stream for the named events.
	read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number
	Read a data from the stream.
	write(data: Array): Number
	Write data to the stream.

Method Detail

close(): Void

Description: Close the stream.

Events

A close event is issued before closing the stream.

flush(dir: Number = BOTH): Void

Description: Flush the stream and underlying streams. A supplied flush direction argument modifies the effect of this call. If direction is set to Stream.READ, then all read data is discarded. If direction is set to Stream.WRITE, any buffered data is written. Stream.BOTH will cause both directions to be flushed. If the stream is in sync mode, this call will block until all data is written. If the stream is in async mode, it will attempt to write all data but will return immediately. Defaults to Stream.WRITE.

Parameters

dir: Number

Direction to flush. Set to READ WRITE or BOTH. [default: BOTH]

off(name, observer: Function): Void

Description: Remove an observer from the stream.

Parameters

name	Event name previously used with observe. The name may be an array of events.
observer: Function	Observer function previously used with observe.

on(name, observer: Function): Stream

Description: Add an observer to the stream for the named events.

Parameters

name: [String\|Array]	Name of the event to listen for. The name may be an array of events.
observer: Function	Callback observer function. The function is called with the following signature: function observer(event: String, ...args): Void.

Events

readable	Issued when the stream becomes readable.
writable	Issued when the stream becomes writable.
close	Issued when stream is being closed. 8.

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

Description: Read a data from the stream. If data is available, the call will return immediately. 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. In this case a "readable" event will be issued when data is available for reading.

Parameters

buffer: ByteArray	Destination byte array for read data.
offset: Number	Offset in the byte array to place the data. If the offset is -1, then data is appended to the buffer write position which is then updated. If offset is >= 0, the data is read to the offset and the read pointer is set to the offset and the write pointer to one past the end of the data just read. [default: 0]
count: Number	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. If the buffer is of a fixed size, ready only what will fit into the buffer. [default: -1]

Events

readable	Issued when there is new read data available.
writable	Issued when the stream becomes empty. `.

Returns: A count of the bytes actually read. Returns null on EOF or errors.

write(data: Array): Number

Description: Write data to the stream. If the stream can accept all the write data, the call returns immediately with the number of bytes 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 buffer the data and return immediately. Some streams will require a flush() call to actually send the data. A "writable" event will be issued when the stream can again absorb more data.

Parameters

data: Array

Data to write.

Events

readable	Issued when data is written and a consumer can read without blocking.
writable	Issued when the stream becomes empty and it is ready to be written to.

Returns: A count of the bytes actually written.

Throws: IOError: if there is an I/O error.