The following shows stream module APIs available for each platform.
| Linux (Ubuntu) |
Raspbian (Raspberry Pi) |
NuttX (STM32F4-Discovery) |
|
|---|---|---|---|
| readable.isPaused | O | O | O |
| readable.pause | O | O | O |
| readable.read | O | O | O |
| readable.resume | O | O | O |
| writable.end | O | O | O |
| writable.write | O | O | O |
A stream is an abstract interface for working with streaming data. Streams can be readable, writable, or both (duplex). All streams are instances of EventEmitter.
This method is only for implementing a new stream type.
This function registers the common properties of all streams.
Example
var Stream = require('stream').Stream;
var stream = new Stream();
stream.read = function () {
// A custom read function.
}Readable stream is an abstraction for a data source from which data will be read. At any time a readable stream operates in one of two modes: flowing and paused. All streams begin in paused mode.
In paused mode the stream emits 'readable'
event every time a new data is available for read. This data can
be read by calling the readable.read()
function. A stream can be switched to paused mode by calling
the readable.pause() function.
In flowing mode the stream emits 'data' events
every time when data is received. The data buffer is passed to
the callback function. A stream can be switched to flowing mode
by calling the readable.resume() function
or by adding a 'data' event handler.
Supported events:
Emitted when the underlying resource has been closed and no more
events will be emitted. Not all Readable
streams will emit the 'close' event.
chunk{Buffer|string}
Emitted when the stream passes the ownership of the data to a consumer. Only streams in flowing mode emit this event.
A stream can be switched to flowing mode by calling the
readable.resume() function or by adding
a 'data' event handler.
Example
var Readable = require('stream').Readable;
var readable = new Readable();
readable.on('data', function (chunk) {
// prints: data received: message
console.log('data received: ' + chunk);
})
readable.push("message");Emitted when there is no more data to be consumed from the stream.
Example
var Readable = require('stream').Readable;
var readable = new Readable();
readable.on('end', function () {
// prints: no more data
console.log('no more data');
})
readable.push(null);error{Object}
Emitted when an error is detected by the readable stream. This event may occure any time.
Emitted when there is data available to be read from the stream. This event will also be emitted once the end of the stream data has been reached but before the 'end' event is emitted.
Example
var Readable = require('stream').Readable;
var readable = new Readable();
readable.on('readable', function () {
// prints:.
console.log('data received: ' + this.read());
})
readable.push('message');options{Object}defaultEncoding{string} Default:utf8
This method is only for implementing a new
Readable stream type.
This function registers the common properties
of Readable streams.
The options object allows passing configuration
arguments. The Readable constructor only supports
a few members of the options object but descendants
may supports more of them.
Example
var Readable = require('stream').Readable;
var readable = new Readable({ defaultEncoding: 'utf8' });- Returns: {boolean}
Returns true if the Readable
stream is in paused mode. Otherwise the stream is in
flowing mode. By default the stream starts in paused mode.
Example
var Readable = require('stream').Readable;
var readable = new Readable();
// prints: true
console.log(readable.isPaused());- Returns: {Readable}
Stops emitting 'data' events if the
stream is in flowing mode and sets paused mode. No
effect otherwise.
Example
var Readable = require('stream').Readable;
var readable = new Readable();
readable.pause();size{number} Specify how much data will be read.- Returns: {Buffer|null}
The readable.read() method pulls some data out of the
internal buffer and returns it. If no data is available
null is returned instead.
Note: currently all data must be read.
Example
var Readable = require('stream').Readable;
var readable = new Readable();
// prints: null
console.log(readable.read());
readable.push('message');
// prints: message
console.log(readable.read());- Returns: {Readable}
Starts emitting 'data' events if the
stream is in paused mode and sets flowing mode. No effect
otherwise.
Example
var Readable = require('stream').Readable;
var readable = new Readable();
readable.resume();chunk{Buffer|string}
This method is only for implementing a new
Readable stream type.
Push a chunk of data to the underlying Buffer of
this stream. The data can be read by using
either readable.read() method
or 'data' event of this stream.
Example
var Readable = require('stream').Readable;
var readable = new Readable();
readable.push('message');
// prints: message
console.log(readable.read());Writable stream is an abstraction for a destination
to which data is written. Several functions of the
Stream.Writable class are abstract interfaces and
descendants can override them. The
new Stream.Writable()
constructor must be used for initializing a
writable stream and
writable._write()
method are required to be implemented.
Supported events:
If writable.write()
returns false the stream emits a drain event when
it is appropriate to resume writing data into the stream.
Example
var Writable = require('stream').Writable;
// Buffer is full after 1 byte of data.
var writable = new Writable({ highWaterMark:1 });
writable._write = function(chunk, callback, onwrite) {
onwrite();
}
// Writes 1 byte data into the stream.
writable.write("X");
writable.on('drain', function() {
// prints: can continue writing
console.log('can continue writing');
});
writable._readyToWrite();err{Error}
Emitted if an error occures during writing the data.
Emitted after writable.end()
has been called and all pending data has been flushed.
Example
var Writable = require('stream').Writable;
var writable = new Writable();
writable.on('finish', function() {
// prints: end of writing
console.log('end of writing');
});
writable.end();options{Object}highWaterMark{number}
This method is only for implementing a new
Writable stream type.
This function registers the common properties
of Writable streams.
When the size of the internal buffer reaches
options.highWaterMark the
writable.write()
method starts returning with false and the data
should be drained before further data is written.
Example
var Writable = require('stream').Writable;
var writable = new Writable({ highWaterMark:256 });chunk{Buffer|string} Final data to write.callback{Function}
Calling this function signals that no more data will
be written to the Writable. The optional chunk
argument allows writing a final chunk of data.
If chunk is null no data is written.
The optional callback function is attached
as a listener for the 'finish' event.
Example
var Writable = require('stream').Writable;
var writable = new Writable();
writable.end();chunk{Buffer|string} Data to write.callback{Function} Called when this chunk of data is flushed.- Returns: {boolean}
Converts chunk into a sequence of bytes and writes this data
to the stream. An optional callback function is called when
the data is flushed.
The returned value is true if writing can be continued
right after calling this method. Otherwise the returned
value is false and no data should be written until the
'drain' event is received.
Example
var Writable = require('stream').Writable;
var writable = new Writable();
writable.write("String");This method is only for implementing a new
Writable stream type.
This method informs the Writable
stream that the implementation is ready for receiving data.
Example
var Writable = require('stream').Writable;
var writable = new Writable();
writable._readyToWrite();chunk{Buffer|string} The data to be written by the stream.callback{Function} Callback to be called when the chunk of data is flushed.onwrite{Function} Internal Callback to be called for when the chunk of data is flushed.
This method is only for implementing a new
Writable stream type.
This internal method is called by the
Writable stream and the implementation
must override it. The data to be written is passed as the
chunk argument. After the operation is completed, both
callback and onwrite function should be called.
Example
var Writable = require('stream').Writable;
var writable = new Writable();
writable._write = function(chunk, callback, onwrite) {
// prints: message
console.log(chunk);
onwrite();
if (callback)
callback();
}
writable._readyToWrite();
writable.write('message');Duplex streams are streams that implement both the Readable and Writable interfaces.