lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: multiple improvements in Stream docs 

Add missing links, remove duplicate ones, fix constants and functions styling.
Minor lexical corrections.

PR-URL: https://github.com/nodejs/node/pull/5009
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
v4.x
Alexander Makarenko 9 years ago
committed by Myles Borins
parent
0acb8e25aa
commit
7ebef46a60
1 changed files with 271 additions and 266 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 433
      doc/api/stream.markdown

433
doc/api/stream.markdown
View File

@ -3,9 +3,9 @@
Stability: 2 - Stable
A stream is an abstract interface implemented by various objects in
Node.js. For example a [request to an HTTP server][] is a stream, as is
[`stdout`][]. Streams are readable, writable, or both. All streams are
instances of [`EventEmitter`][].
Node.js. For example a [request to an HTTP server][http-incoming-message] is a
stream, as is [`process.stdout`][]. Streams are readable, writable, or both. All
streams are instances of [`EventEmitter`][].
You can load the Stream base classes by doing `require('stream')`.
There are base classes provided for [Readable][] streams, [Writable][]
@ -16,8 +16,8 @@ This document is split up into 3 sections:
1. The first section explains the parts of the API that you need to be
aware of to use streams in your programs.
2. The second section explains the parts of the API that you need to
use if you implement your own custom streams yourself. The API is
designed to make this easy for you to do.
use if you implement your own custom streams yourself. The API is designed to
make this easy for you to do.
3. The third section goes into more depth about how streams work,
including some of the internal mechanisms and functions that you
should probably not modify unless you definitely know what you are
@ -97,9 +97,9 @@ Duplex streams are streams that implement both the [Readable][] and
Examples of Duplex streams include:
* [tcp sockets][]
* [zlib streams][]
* [crypto streams][]
* [TCP sockets][]
* [zlib streams][zlib]
* [crypto streams][crypto]
### Class: stream.Readable
@ -115,41 +115,42 @@ you are ready to receive it.
Readable streams have two "modes": a **flowing mode** and a **paused
mode**. When in flowing mode, data is read from the underlying system
and provided to your program as fast as possible. In paused mode, you
must explicitly call `stream.read()` to get chunks of data out.
must explicitly call [`stream.read()`][stream-read] to get chunks of data out.
Streams start out in paused mode.
**Note**: If no data event handlers are attached, and there are no
[`pipe()`][] destinations, and the stream is switched into flowing
[`stream.pipe()`][] destinations, and the stream is switched into flowing
mode, then data will be lost.
You can switch to flowing mode by doing any of the following:
* Adding a [`'data'`][] event handler to listen for data.
* Calling the [`resume()`][] method to explicitly open the flow.
* Calling the [`pipe()`][] method to send the data to a [Writable][].
* Calling the [`stream.resume()`][stream-resume] method to explicitly open the
flow.
* Calling the [`stream.pipe()`][] method to send the data to a [Writable][].
You can switch back to paused mode by doing either of the following:
* If there are no pipe destinations, by calling the [`pause()`][]
method.
* If there are no pipe destinations, by calling the
[`stream.pause()`][stream-pause] method.
* If there are pipe destinations, by removing any [`'data'`][] event
handlers, and removing all pipe destinations by calling the
[`unpipe()`][] method.
[`stream.unpipe()`][] method.
Note that, for backwards compatibility reasons, removing `'data'`
Note that, for backwards compatibility reasons, removing [`'data'`][]
event handlers will **not** automatically pause the stream. Also, if
there are piped destinations, then calling `pause()` will not
guarantee that the stream will *remain* paused once those
there are piped destinations, then calling [`stream.pause()`][stream-pause] will
not guarantee that the stream will *remain* paused once those
destinations drain and ask for more data.
Examples of readable streams include:
* [http responses, on the client][]
* [http requests, on the server][]
* [HTTP responses, on the client][http-incoming-message]
* [HTTP requests, on the server][http-incoming-message]
* [fs read streams][]
* [zlib streams][]
* [crypto streams][]
* [tcp sockets][]
* [zlib streams][zlib]
* [crypto streams][crypto]
* [TCP sockets][]
* [child process stdout and stderr][]
* [`process.stdin`][]
@ -185,7 +186,8 @@ This event fires when there will be no more data to read.
Note that the `'end'` event **will not fire** unless the data is
completely consumed. This can be done by switching into flowing mode,
or by calling `read()` repeatedly until you get to the end.
or by calling [`stream.read()`][stream-read] repeatedly until you get to the
end.
```js
var readable = getReadableStreamSomehow();
@ -227,9 +229,9 @@ sole exception of the last one, on end-of-stream.
The `'readable'` event indicates that the stream has new information:
either new data is available or the end of the stream has been reached.
In the former case, `.read()` will return that data. In the latter case,
`.read()` will return null. For instance, in the following example, `foo.txt`
is an empty file:
In the former case, [`stream.read()`][stream-read] will return that data. In the
latter case, [`stream.read()`][stream-read] will return null. For instance, in
the following example, `foo.txt` is an empty file:
```js
const fs = require('fs');
@ -255,8 +257,8 @@ end
* Return: `Boolean`
This method returns whether or not the `readable` has been **explicitly**
paused by client code (using `readable.pause()` without a corresponding
`readable.resume()`).
paused by client code (using [`stream.pause()`][stream-pause] without a
corresponding [`stream.resume()`][stream-resume]).
```js
var readable = new stream.Readable
@ -273,7 +275,7 @@ readable.isPaused() // === false
* Return: `this`
This method will cause a stream in flowing mode to stop emitting
`'data'` events, switching out of flowing mode. Any data that becomes
[`'data'`][] events, switching out of flowing mode. Any data that becomes
available will remain in the internal buffer.
```js
@ -324,9 +326,9 @@ For example, emulating the Unix `cat` command:
process.stdin.pipe(process.stdout);
```
By default [`end()`][] is called on the destination when the source stream
emits `end`, so that `destination` is no longer writable. Pass `{ end:
false }` as `options` to keep the destination stream open.
By default [`stream.end()`][stream-end] is called on the destination when the
source stream emits [`'end'`][], so that `destination` is no longer writable.
Pass `{ end: false }` as `options` to keep the destination stream open.
This keeps `writer` open so that "Goodbye" can be written at the
end.
@ -338,7 +340,7 @@ reader.on('end', () => {
});
```
Note that `process.stderr` and `process.stdout` are never closed until
Note that [`process.stderr`][] and [`process.stdout`][] are never closed until
the process exits, regardless of the specified options.
#### readable.read([size])
@ -375,20 +377,20 @@ readable.on('readable', () => {
If this method returns a data chunk, then it will also trigger the
emission of a [`'data'`][] event.
Note that calling `readable.read([size])` after the `'end'` event has been
triggered will return `null`. No runtime error will be raised.
Note that calling [`stream.read([size])`][stream-read] after the [`'end'`][]
event has been triggered will return `null`. No runtime error will be raised.
#### readable.resume()
* Return: `this`
This method will cause the readable stream to resume emitting `data`
This method will cause the readable stream to resume emitting [`'data'`][]
events.
This method will switch the stream into flowing mode. If you do *not*
want to consume the data from a stream, but you *do* want to get to
its `'end'` event, you can call [`readable.resume()`][] to open the flow of
data.
its [`'end'`][] event, you can call [`stream.resume()`][stream-resume] to open
the flow of data.
```js
var readable = getReadableStreamSomehow();
@ -403,16 +405,15 @@ readable.on('end', () => {
* `encoding` {String} The encoding to use.
* Return: `this`
Call this function to cause the stream to return strings of the
specified encoding instead of Buffer objects. For example, if you do
`readable.setEncoding('utf8')`, then the output data will be
interpreted as UTF-8 data, and returned as strings. If you do
`readable.setEncoding('hex')`, then the data will be encoded in
hexadecimal string format.
Call this function to cause the stream to return strings of the specified
encoding instead of Buffer objects. For example, if you do
`readable.setEncoding('utf8')`, then the output data will be interpreted as
UTF-8 data, and returned as strings. If you do `readable.setEncoding('hex')`,
then the data will be encoded in hexadecimal string format.
This properly handles multi-byte characters that would otherwise be
potentially mangled if you simply pulled the Buffers directly and
called `buf.toString(encoding)` on them. If you want to read the data
called [`buf.toString(encoding)`][] on them. If you want to read the data
as strings, always use this method.
```js
@ -428,7 +429,8 @@ readable.on('data', (chunk) => {
* `destination` {[Writable][] Stream} Optional specific stream to unpipe
This method will remove the hooks set up for a previous `pipe()` call.
This method will remove the hooks set up for a previous [`stream.pipe()`][]
call.
If the destination is not specified, then all pipes are removed.
@ -458,7 +460,7 @@ parser, which needs to "un-consume" some data that it has
optimistically pulled out of the source, so that the stream can be
passed on to some other party.
Note that `stream.unshift(chunk)` cannot be called after the `'end'` event
Note that `stream.unshift(chunk)` cannot be called after the [`'end'`][] event
has been triggered; a runtime error will be raised.
If you find that you must often call `stream.unshift(chunk)` in your
@ -500,13 +502,14 @@ function parseHeader(stream, callback) {
}
```
Note that, unlike `stream.push(chunk)`, `stream.unshift(chunk)` will not
end the reading process by resetting the internal reading state of the
stream. This can cause unexpected results if `unshift` is called during a
read (i.e. from within a `_read` implementation on a custom stream). Following
the call to `unshift` with an immediate `stream.push('')` will reset the
reading state appropriately, however it is best to simply avoid calling
`unshift` while in the process of performing a read.
Note that, unlike [`stream.push(chunk)`][stream-push], `stream.unshift(chunk)`
will not end the reading process by resetting the internal reading state of the
stream. This can cause unexpected results if `unshift()` is called during a
read (i.e. from within a [`stream._read()`][stream-_read] implementation on a
custom stream). Following the call to `unshift()` with an immediate
[`stream.push('')`][stream-push] will reset the reading state appropriately,
however it is best to simply avoid calling `unshift()` while in the process of
performing a read.
#### readable.wrap(stream)
@ -516,10 +519,10 @@ Versions of Node.js prior to v0.10 had streams that did not implement the
entire Streams API as it is today. (See [Compatibility][] for
more information.)
If you are using an older Node.js library that emits `'data'` events and
has a [`pause()`][] method that is advisory only, then you can use the
`wrap()` method to create a [Readable][] stream that uses the old stream
as its data source.
If you are using an older Node.js library that emits [`'data'`][] events and
has a [`stream.pause()`][stream-pause] method that is advisory only, then you
can use the `wrap()` method to create a [Readable][] stream that uses the old
stream as its data source.
You will very rarely ever need to call this function, but it exists
as a convenience for interacting with old Node.js programs and libraries.
@ -545,8 +548,8 @@ computed from the input. They implement both the [Readable][] and
Examples of Transform streams include:
* [zlib streams][]
* [crypto streams][]
* [zlib streams][zlib]
* [crypto streams][crypto]
### Class: stream.Writable
@ -557,19 +560,19 @@ that you are writing data *to*.
Examples of writable streams include:
* [http requests, on the client][]
* [http responses, on the server][]
* [HTTP requests, on the client][]
* [HTTP responses, on the server][]
* [fs write streams][]
* [zlib streams][]
* [crypto streams][]
* [tcp sockets][]
* [zlib streams][zlib]
* [crypto streams][crypto]
* [TCP sockets][]
* [child process stdin][]
* [`process.stdout`][], [`process.stderr`][]
#### Event: 'drain'
If a [`writable.write(chunk)`][] call returns false, then the `'drain'`
event will indicate when it is appropriate to begin writing more data
If a [`stream.write(chunk)`][stream-write] call returns `false`, then the
`'drain'` event will indicate when it is appropriate to begin writing more data
to the stream.
```js
@ -608,8 +611,8 @@ Emitted if there was an error when writing or piping data.
#### Event: 'finish'
When the [`end()`][] method has been called, and all data has been flushed
to the underlying system, this event is emitted.
When the [`stream.end()`][stream-end] method has been called, and all data has
been flushed to the underlying system, this event is emitted.
```javascript
var writer = getWritableStreamSomehow();
@ -626,7 +629,7 @@ writer.on('finish', () => {
* `src` {[Readable][] Stream} source stream that is piping to this writable
This is emitted whenever the `pipe()` method is called on a readable
This is emitted whenever the [`stream.pipe()`][] method is called on a readable
stream, adding this writable to its set of destinations.
```js
@ -641,9 +644,10 @@ reader.pipe(writer);
#### Event: 'unpipe'
* `src` {[Readable][] Stream} The source stream that [unpiped][] this writable
* `src` {[Readable][] Stream} The source stream that
[unpiped][`stream.unpipe()`] this writable
This is emitted whenever the [`unpipe()`][] method is called on a
This is emitted whenever the [`stream.unpipe()`][] method is called on a
readable stream, removing this writable from its set of destinations.
```js
@ -661,7 +665,8 @@ reader.unpipe(writer);
Forces buffering of all writes.
Buffered data will be flushed either at `.uncork()` or at `.end()` call.
Buffered data will be flushed either at [`stream.uncork()`][] or at
[`stream.end()`][stream-end] call.
#### writable.end([chunk][, encoding][, callback])
@ -669,10 +674,11 @@ Buffered data will be flushed either at `.uncork()` or at `.end()` call.
* `encoding` {String} The encoding, if `chunk` is a String
* `callback` {Function} Optional callback for when the stream is finished
Call this method when no more data will be written to the stream. If
supplied, the callback is attached as a listener on the `'finish'` event.
Call this method when no more data will be written to the stream. If supplied,
the callback is attached as a listener on the [`'finish'`][] event.
Calling [`write()`][] after calling [`end()`][] will raise an error.
Calling [`stream.write()`][stream-write] after calling
[`stream.end()`][stream-end] will raise an error.
```js
// write 'hello, ' and then end with 'world!'
@ -690,14 +696,14 @@ Sets the default encoding for a writable stream.
#### writable.uncork()
Flush all data, buffered since `.cork()` call.
Flush all data, buffered since [`stream.cork()`][] call.
#### writable.write(chunk[, encoding][, callback])
* `chunk` {String | Buffer} The data to write
* `encoding` {String} The encoding, if `chunk` is a String
* `callback` {Function} Callback for when this chunk of data is flushed
* Returns: {Boolean} True if the data was handled completely.
* Returns: {Boolean} `true` if the data was handled completely.
This method writes some data to the underlying system, and calls the
supplied callback once the data has been fully handled.
@ -709,7 +715,7 @@ If the data had to be buffered internally, then it will return
This return value is strictly advisory. You MAY continue to write,
even if it returns `false`. However, writes will be buffered in
memory, so it is best not to do this excessively. Instead, wait for
the `'drain'` event before writing more data.
the [`'drain'`][] event before writing more data.
## API for Stream Implementors
@ -719,7 +725,7 @@ the `'drain'` event before writing more data.
To implement any sort of stream, the pattern is the same:
1. Extend the appropriate parent class in your own subclass. (The
[`util.inherits`][] method is particularly helpful for this.)
[`util.inherits()`][] method is particularly helpful for this.)
2. Call the appropriate parent class constructor in your constructor,
to be sure that the internal mechanisms are set up properly.
3. Implement one or more specific methods, as detailed below.
@ -749,7 +755,7 @@ of stream class you are writing:
<p>[Readable](#stream_class_stream_readable_1)</p>
</td>
<td>
<p><code>[_read][]</code></p>
<p><code>[_read][stream-_read]</code></p>
</td>
</tr>
<tr>
@ -760,7 +766,7 @@ of stream class you are writing:
<p>[Writable](#stream_class_stream_writable_1)</p>
</td>
<td>
<p><code>[_write][]</code>, <code>[_writev][]</code></p>
<p><code>[_write][stream-_write]</code>, <code>[_writev][stream-_writev]</code></p>
</td>
</tr>
<tr>
@ -771,7 +777,7 @@ of stream class you are writing:
<p>[Duplex](#stream_class_stream_duplex_1)</p>
</td>
<td>
<p><code>[_read][]</code>, <code>[_write][]</code>, <code>[_writev][]</code></p>
<p><code>[_read][stream-_read]</code>, <code>[_write][stream-_write]</code>, <code>[_writev][stream-_writev]</code></p>
</td>
</tr>
<tr>
@ -782,45 +788,45 @@ of stream class you are writing:
<p>[Transform](#stream_class_stream_transform_1)</p>
</td>
<td>
<p><code>[_transform][]</code>, <code>[_flush][]</code></p>
<p><code>[_transform][stream-_transform]</code>, <code>[_flush][stream-_flush]</code></p>
</td>
</tr>
</table>
In your implementation code, it is very important to never call the
methods described in [API for Stream Consumers][]. Otherwise, you
can potentially cause adverse side effects in programs that consume
your streaming interfaces.
In your implementation code, it is very important to never call the methods
described in [API for Stream Consumers][]. Otherwise, you can potentially cause
adverse side effects in programs that consume your streaming interfaces.
### Class: stream.Duplex
<!--type=class-->
A "duplex" stream is one that is both Readable and Writable, such as a
TCP socket connection.
A "duplex" stream is one that is both Readable and Writable, such as a TCP
socket connection.
Note that `stream.Duplex` is an abstract class designed to be extended
with an underlying implementation of the `_read(size)` and
[`_write(chunk, encoding, callback)`][] methods as you would with a
Readable or Writable stream class.
with an underlying implementation of the [`stream._read(size)`][stream-_read]
and [`stream._write(chunk, encoding, callback)`][stream-_write] methods as you
would with a Readable or Writable stream class.
Since JavaScript doesn't have multiple prototypal inheritance, this
class prototypally inherits from Readable, and then parasitically from
Writable. It is thus up to the user to implement both the lowlevel
`_read(n)` method as well as the lowlevel
[`_write(chunk, encoding, callback)`][] method on extension duplex classes.
Since JavaScript doesn't have multiple prototypal inheritance, this class
prototypally inherits from Readable, and then parasitically from Writable. It is
thus up to the user to implement both the low-level
[`stream._read(n)`][stream-_read] method as well as the low-level
[`stream._write(chunk, encoding, callback)`][stream-_write] method on extension
duplex classes.
#### new stream.Duplex(options)
* `options` {Object} Passed to both Writable and Readable
constructors. Also has the following fields:
* `allowHalfOpen` {Boolean} Default=true. If set to `false`, then
* `allowHalfOpen` {Boolean} Default = `true`. If set to `false`, then
the stream will automatically end the readable side when the
writable side ends and vice versa.
* `readableObjectMode` {Boolean} Default=false. Sets `objectMode`
* `readableObjectMode` {Boolean} Default = `false`. Sets `objectMode`
for readable side of the stream. Has no effect if `objectMode`
is `true`.
* `writableObjectMode` {Boolean} Default=false. Sets `objectMode`
* `writableObjectMode` {Boolean} Default = `false`. Sets `objectMode`
for writable side of the stream. Has no effect if `objectMode`
is `true`.
@ -840,7 +846,7 @@ it can come in handy as a building block for novel sorts of streams.
<!--type=class-->
`stream.Readable` is an abstract class designed to be extended with an
underlying implementation of the [`_read(size)`][] method.
underlying implementation of the [`stream._read(size)`][stream-_read] method.
Please see [API for Stream Consumers][] for how to consume
streams in your programs. What follows is an explanation of how to
@ -851,13 +857,14 @@ implement Readable streams in your programs.
* `options` {Object}
* `highWaterMark` {Number} The maximum number of bytes to store in
the internal buffer before ceasing to read from the underlying
resource. Default=16kb, or 16 for `objectMode` streams
resource. Default = `16384` (16kb), or `16` for `objectMode` streams
* `encoding` {String} If specified, then buffers will be decoded to
strings using the specified encoding. Default=null
strings using the specified encoding. Default = `null`
* `objectMode` {Boolean} Whether this stream should behave
as a stream of objects. Meaning that stream.read(n) returns
a single value instead of a Buffer of size n. Default=false
* `read` {Function} Implementation for the [`_read()`][] method.
as a stream of objects. Meaning that [`stream.read(n)`][stream-read] returns
a single value instead of a Buffer of size n. Default = `false`
* `read` {Function} Implementation for the [`stream._read()`][stream-_read]
method.
In classes that extend the Readable class, make sure to call the
Readable constructor so that the buffering settings can be properly
@ -874,22 +881,23 @@ class that defines it and should only be called by the internal Readable
class methods. All Readable stream implementations must provide a \_read
method to fetch data from the underlying resource.
When \_read is called, if data is available from the resource, `_read` should
start pushing that data into the read queue by calling `this.push(dataChunk)`.
`_read` should continue reading from the resource and pushing data until push
returns false, at which point it should stop reading from the resource. Only
when \_read is called again after it has stopped should it start reading
more data from the resource and pushing that data onto the queue.
When `_read()` is called, if data is available from the resource, the `_read()`
implementation should start pushing that data into the read queue by calling
[`this.push(dataChunk)`][stream-push]. `_read()` should continue reading from
the resource and pushing data until push returns `false`, at which point it
should stop reading from the resource. Only when `_read()` is called again after
it has stopped should it start reading more data from the resource and pushing
that data onto the queue.
Note: once the `_read()` method is called, it will not be called again until
the `push` method is called.
the [`stream.push()`][stream-push] method is called.
The `size` argument is advisory. Implementations where a "read" is a
single call that returns data can use this to know how much data to
fetch. Implementations where that is not relevant, such as TCP or
TLS, may ignore this argument, and simply provide data whenever it
becomes available. There is no need, for example to "wait" until
`size` bytes are available before calling [`stream.push(chunk)`][].
`size` bytes are available before calling [`stream.push(chunk)`][stream-push].
#### readable.push(chunk[, encoding])
@ -906,8 +914,8 @@ into the queue for subsequent stream processors to consume. If `null` is
passed, it signals the end of the stream (EOF), after which no more data
can be written.
The data added with `push` can be pulled out by calling the `read()` method
when the `'readable'` event fires.
The data added with `push()` can be pulled out by calling the
[`stream.read()`][stream-read] method when the [`'readable'`][] event fires.
This API is designed to be as flexible as possible. For example,
you may be wrapping a lower-level source which has some sort of
@ -1103,16 +1111,19 @@ Hash stream will only ever have a single chunk of output which is
provided when the input is ended. A zlib stream will produce output
that is either much smaller or much larger than its input.
Rather than implement the [`_read()`][] and [`_write()`][] methods, Transform
classes must implement the `_transform()` method, and may optionally
also implement the `_flush()` method. (See below.)
Rather than implement the [`stream._read()`][stream-_read] and
[`stream._write()`][stream-_write] methods, Transform classes must implement the
[`stream._transform()`][stream-_transform] method, and may optionally
also implement the [`stream._flush()`][stream-_flush] method. (See below.)
#### new stream.Transform([options])
* `options` {Object} Passed to both Writable and Readable
constructors. Also has the following fields:
* `transform` {Function} Implementation for the [`_transform()`][] method.
* `flush` {Function} Implementation for the [`_flush()`][] method.
* `transform` {Function} Implementation for the
[`stream._transform()`][stream-_transform] method.
* `flush` {Function} Implementation for the [`stream._flush()`][stream-_flush]
method.
In classes that extend the Transform class, make sure to call the
constructor so that the buffering settings can be properly
@ -1122,9 +1133,10 @@ initialized.
The [`'finish'`][] and [`'end'`][] events are from the parent Writable
and Readable classes respectively. The `'finish'` event is fired after
`.end()` is called and all chunks have been processed by `_transform`,
`end` is fired after all data has been output which is after the callback
in `_flush` has been called.
[`stream.end()`][stream-end] is called and all chunks have been processed by
[`stream._transform()`][stream-_transform], `'end'` is fired after all data has
been output which is after the callback in [`stream._flush()`][stream-_flush]
has been called.
#### transform._flush(callback)
@ -1141,12 +1153,12 @@ stream will store up some internal state so that it can optimally
compress the output. At the end, however, it needs to do the best it
can with what is left, so that the data will be complete.
In those cases, you can implement a `_flush` method, which will be
In those cases, you can implement a `_flush()` method, which will be
called at the very end, after all the written data is consumed, but
before emitting `end` to signal the end of the readable side. Just
like with `_transform`, call `transform.push(chunk)` zero or more
times, as appropriate, and call `callback` when the flush operation is
complete.
before emitting [`'end'`][] to signal the end of the readable side. Just
like with [`stream._transform()`][stream-_transform], call
`transform.push(chunk)` zero or more times, as appropriate, and call `callback`
when the flush operation is complete.
This method is prefixed with an underscore because it is internal to
the class that defines it, and should not be called directly by user
@ -1167,10 +1179,10 @@ Note: **This function MUST NOT be called directly.** It should be
implemented by child classes, and called by the internal Transform
class methods only.
All Transform stream implementations must provide a `_transform`
All Transform stream implementations must provide a `_transform()`
method to accept input and produce output.
`_transform` should do whatever has to be done in this specific
`_transform()` should do whatever has to be done in this specific
Transform class, to handle the bytes being written, and pass them off
to the readable portion of the interface. Do asynchronous I/O,
process things, and so on.
@ -1285,7 +1297,8 @@ SimpleProtocol.prototype._transform = function(chunk, encoding, done) {
<!--type=class-->
`stream.Writable` is an abstract class designed to be extended with an
underlying implementation of the [`_write(chunk, encoding, callback)`][] method.
underlying implementation of the
[`stream._write(chunk, encoding, callback)`][stream-_write] method.
Please see [API for Stream Consumers][] for how to consume
writable streams in your programs. What follows is an explanation of
@ -1294,15 +1307,20 @@ how to implement Writable streams in your programs.
#### new stream.Writable([options])
* `options` {Object}
* `highWaterMark` {Number} Buffer level when [`write()`][] starts
returning false. Default=16kb, or 16 for `objectMode` streams
* `highWaterMark` {Number} Buffer level when
[`stream.write()`][stream-write] starts returning `false`. Default = `16384`
(16kb), or `16` for `objectMode` streams.
* `decodeStrings` {Boolean} Whether or not to decode strings into
Buffers before passing them to [`_write()`][]. Default=true
* `objectMode` {Boolean} Whether or not the `write(anyObj)` is
a valid operation. If set you can write arbitrary data instead
of only `Buffer` / `String` data. Default=false
* `write` {Function} Implementation for the [`_write()`][] method.
* `writev` {Function} Implementation for the [`_writev()`][] method.
Buffers before passing them to [`stream._write()`][stream-_write].
Default = `true`
* `objectMode` {Boolean} Whether or not the
[`stream.write(anyObj)`][stream-write] is a valid operation. If set you can
write arbitrary data instead of only `Buffer` / `String` data.
Default = `false`
* `write` {Function} Implementation for the
[`stream._write()`][stream-_write] method.
* `writev` {Function} Implementation for the
[`stream._writev()`][stream-_writev] method.
In classes that extend the Writable class, make sure to call the
constructor so that the buffering settings can be properly
@ -1318,8 +1336,9 @@ initialized.
* `callback` {Function} Call this function (optionally with an error
argument) when you are done processing the supplied chunk.
All Writable stream implementations must provide a [`_write()`][]
method to send data to the underlying resource.
All Writable stream implementations must provide a
[`stream._write()`][stream-_write] method to send data to the underlying
resource.
Note: **This function MUST NOT be called directly.** It should be
implemented by child classes, and called by the internal Writable
@ -1361,7 +1380,8 @@ that are buffered in the write queue.
<!--type=misc-->
In simple cases there is now the added benefit of being able to construct a stream without inheritance.
In simple cases there is now the added benefit of being able to construct a
stream without inheritance.
This can be done by passing the appropriate methods as constructor options:
@ -1483,14 +1503,14 @@ The amount of data that will potentially be buffered depends on the
`highWaterMark` option which is passed into the constructor.
Buffering in Readable streams happens when the implementation calls
[`stream.push(chunk)`][]. If the consumer of the Stream does not call
`stream.read()`, then the data will sit in the internal queue until it
is consumed.
[`stream.push(chunk)`][stream-push]. If the consumer of the Stream does not
call [`stream.read()`][stream-read], then the data will sit in the internal
queue until it is consumed.
Buffering in Writable streams happens when the user calls
[`stream.write(chunk)`][] repeatedly, even when `write()` returns `false`.
[`stream.write(chunk)`][stream-write] repeatedly, even when it returns `false`.
The purpose of streams, especially with the `pipe()` method, is to
The purpose of streams, especially with the [`stream.pipe()`][] method, is to
limit the buffering of data to acceptable levels, so that sources and
destinations of varying speed will not overwhelm the available memory.
@ -1501,26 +1521,27 @@ destinations of varying speed will not overwhelm the available memory.
In versions of Node.js prior to v0.10, the Readable stream interface was
simpler, but also less powerful and less useful.
* Rather than waiting for you to call the `read()` method, `'data'`
events would start emitting immediately. If you needed to do some
I/O to decide how to handle data, then you had to store the chunks
* Rather than waiting for you to call the [`stream.read()`][stream-read] method,
[`'data'`][] events would start emitting immediately. If you needed to do
some I/O to decide how to handle data, then you had to store the chunks
in some kind of buffer so that they would not be lost.
* The [`pause()`][] method was advisory, rather than guaranteed. This
meant that you still had to be prepared to receive `'data'` events
even when the stream was in a paused state.
* The [`stream.pause()`][stream-pause] method was advisory, rather than
guaranteed. This meant that you still had to be prepared to receive
[`'data'`][] events even when the stream was in a paused state.
In Node.js v0.10, the [Readable][] class was added.
For backwards compatibility with older Node.js programs, Readable streams
switch into "flowing mode" when a `'data'` event handler is added, or
when the [`resume()`][] method is called. The effect is that, even if
you are not using the new `read()` method and `'readable'` event, you
no longer have to worry about losing `'data'` chunks.
switch into "flowing mode" when a [`'data'`][] event handler is added, or
when the [`stream.resume()`][stream-resume] method is called. The effect is
that, even if you are not using the new [`stream.read()`][stream-read] method
and [`'readable'`][] event, you no longer have to worry about losing
[`'data'`][] chunks.
Most programs will continue to function normally. However, this
introduces an edge case in the following conditions:
* No [`'data'`][] event handler is added.
* The [`resume()`][] method is never called.
* The [`stream.resume()`][stream-resume] method is never called.
* The stream is not piped to any writable destination.
For example, consider the following code:
@ -1542,8 +1563,8 @@ In versions of Node.js prior to v0.10, the incoming message data would be
simply discarded. However, in Node.js v0.10 and beyond,
the socket will remain paused forever.
The workaround in this situation is to call the `resume()` method to
start the flow of data:
The workaround in this situation is to call the
[`stream.resume()`][stream-resume] method to start the flow of data:
```js
// Workaround
@ -1561,7 +1582,7 @@ net.createServer((socket) => {
In addition to new Readable streams switching into flowing mode,
pre-v0.10 style streams can be wrapped in a Readable class using the
`wrap()` method.
[`stream.wrap()`][] method.
### Object Mode
@ -1574,16 +1595,16 @@ Streams that are in **object mode** can emit generic JavaScript values
other than Buffers and Strings.
A Readable stream in object mode will always return a single item from
a call to `stream.read(size)`, regardless of what the size argument
is.
a call to [`stream.read(size)`][stream-read], regardless of what the size
argument is.
A Writable stream in object mode will always ignore the `encoding`
argument to `stream.write(data, encoding)`.
argument to [`stream.write(data, encoding)`][stream-write].
The special value `null` still retains its special value for object
mode streams. That is, for object mode readable streams, `null` as a
return value from `stream.read()` indicates that there is no more
data, and [`stream.push(null)`][] will signal the end of stream data
return value from [`stream.read()`][stream-read] indicates that there is no more
data, and [`stream.push(null)`][stream-push] will signal the end of stream data
(`EOF`).
No streams in Node.js core are object mode streams. This pattern is only
@ -1659,8 +1680,8 @@ data. In that case, you can call `stream.read(0)`, which will always
return null.
If the internal read buffer is below the `highWaterMark`, and the
stream is not currently reading, then calling `read(0)` will trigger
a low-level `_read` call.
stream is not currently reading, then calling `stream.read(0)` will trigger
a low-level [`stream._read()`][stream-_read] call.
There is almost never a need to do this. However, you will see some
cases in Node.js's internals where this is done, particularly in the
@ -1670,14 +1691,14 @@ Readable stream class internals.
Pushing a zero-byte string or Buffer (when not in [Object mode][]) has an
interesting side effect. Because it *is* a call to
[`stream.push()`][], it will end the `reading` process. However, it
[`stream.push()`][stream-push], it will end the `reading` process. However, it
does *not* add any data to the readable buffer, so there's nothing for
a user to consume.
Very rarely, there are cases where you have no data to provide now,
but the consumer of your stream (or, perhaps, another bit of your own
code) will know when to check again, by calling `stream.read(0)`. In
those cases, you *may* call `stream.push('')`.
code) will know when to check again, by calling [`stream.read(0)`][stream-read].
In those cases, you *may* call `stream.push('')`.
So far, the only use case for this functionality is in the
[`tls.CryptoStream`][] class, which is deprecated in Node.js/io.js v1.0. If you
@ -1685,66 +1706,50 @@ find that you have to use `stream.push('')`, please consider another
approach, because it almost certainly indicates that something is
horribly wrong.
[_read]: #stream_readable_read_size_1
[_write]: #stream_writable_write_chunk_encoding_callback_1
[`'data'`]: #stream_event_data
[`'drain'`]: #stream_event_drain
[`'end'`]: #stream_event_end
[`'finish'`]: #stream_event_finish
[`_read()`]: #stream_readable_read_size_1
[`_read(size)`]: #stream_readable_read_size_1
[`_write()`]: #stream_writable_write_chunk_encoding_callback_1
[`_write(chunk, encoding, callback)`]: #stream_writable_write_chunk_encoding_callback_1
[`end()`]: #stream_writable_end_chunk_encoding_callback
[`'readable'`]: #stream_event_readable
[`buf.toString(encoding)`]: buffer.html#buffer_buf_tostring_encoding_start_end
[`EventEmitter`]: events.html#events_class_eventemitter
[`pause()`]: #stream_readable_pause
[`pipe()`]: #stream_readable_pipe_destination_options
[`process.stderr`]: process.html#process_process_stderr
[`process.stdin`]: process.html#process_process_stdin
[`process.stdout`]: process.html#process_process_stdout
[`readable.resume()`]: #stream_readable_resume
[`resume()`]: #stream_readable_resume
[`stdout`]: process.html#process_process_stdout
[`stream.push()`]: #stream_readable_push_chunk_encoding
[`stream.push(chunk)`]: #stream_readable_push_chunk_encoding
[`stream.push(null)`]: #stream_readable_push_chunk_encoding
[`stream.write(chunk)`]: #stream_writable_write_chunk_encoding_callback
[`stream.cork()`]: #stream_writable_cork
[`stream.pipe()`]: #stream_readable_pipe_destination_options
[`stream.uncork()`]: #stream_writable_uncork
[`stream.unpipe()`]: #stream_readable_unpipe_destination
[`stream.wrap()`]: #stream_readable_wrap_stream
[`tls.CryptoStream`]: tls.html#tls_class_cryptostream
[`unpipe()`]: #stream_readable_unpipe_destination
[`unpipe()`]: #stream_readable_unpipe_destination
[`util.inherits`]: util.html#util_util_inherits_constructor_superconstructor
[`writable.write(chunk)`]: #stream_writable_write_chunk_encoding_callback
[`write()`]: #stream_writable_write_chunk_encoding_callback
[`write(chunk, encoding, callback)`]: #stream_writable_write_chunk_encoding_callback
[`util.inherits()`]: util.html#util_util_inherits_constructor_superconstructor
[API for Stream Consumers]: #stream_api_for_stream_consumers
[API for Stream Implementors]: #stream_api_for_stream_implementors
[child process stdin]: child_process.html#child_process_child_stdin
[child process stdout and stderr]: child_process.html#child_process_child_stdout
[Compatibility]: #stream_compatibility_with_older_node_js_versions
[crypto streams]: crypto.html
[crypto]: crypto.html
[Duplex]: #stream_class_stream_duplex
[fs read streams]: fs.html#fs_class_fs_readstream
[fs write streams]: fs.html#fs_class_fs_writestream
[http requests, on the client]: http.html#http_class_http_clientrequest
[http requests, on the server]: http.html#http_class_http_incomingmessage
[http responses, on the client]: http.html#http_class_http_incomingmessage
[http responses, on the server]: http.html#http_class_http_serverresponse
[HTTP requests, on the client]: http.html#http_class_http_clientrequest
[HTTP responses, on the server]: http.html#http_class_http_serverresponse
[http-incoming-message]: http.html#http_class_http_incomingmessage
[Object mode]: #stream_object_mode
[Readable]: #stream_class_stream_readable
[request to an HTTP server]: http.html#http_class_http_incomingmessage
[SimpleProtocol v2]: #stream_example_simpleprotocol_parser_v2
[tcp sockets]: net.html#net_class_net_socket
[stream-_flush]: #stream_transform_flush_callback
[stream-_read]: #stream_readable_read_size_1
[stream-_transform]: #stream_transform_transform_chunk_encoding_callback
[stream-_write]: #stream_writable_write_chunk_encoding_callback_1
[stream-_writev]: #stream_writable_writev_chunks_callback
[stream-end]: #stream_writable_end_chunk_encoding_callback
[stream-pause]: #stream_readable_pause
[stream-push]: #stream_readable_push_chunk_encoding
[stream-read]: #stream_readable_read_size
[stream-resume]: #stream_readable_resume
[stream-write]: #stream_writable_write_chunk_encoding_callback
[TCP sockets]: net.html#net_class_net_socket
[Transform]: #stream_class_stream_transform
[unpiped]: #stream_readable_unpipe_destination
[Writable]: #stream_class_stream_writable
[zlib streams]: zlib.html
[zlib]: zlib.html
[_transform]: #stream_transform_transform_chunk_encoding_callback
[`_transform()`]: #stream_transform_transform_chunk_encoding_callback
[`_transform(chunk, encoding, callback)`]: #stream_transform_transform_chunk_encoding_callback
[_flush]: #stream_transform_flush_callback
[`_flush()`]: #stream_transform_flush_callback
[`_flush(callback)`]: #stream_transform_flush_callback
[_writev]: #stream_writable_writev_chunks_callback
[`_writev()`]: #stream_writable_writev_chunks_callback
[`_writev(chunks, callback)`]: #stream_writable_writev_chunks_callback

Write Preview
Loading…
Cancel
Save