Browse files

docs: update some docs related to streams2

- Added about "object mode" into stream.Readable.
- Added 'readable' and read() into net.Socket and http.incomingMessage.
- Fixed missing links.
  • Loading branch information...
1 parent 30b0bc4 commit b8bd2499f6d1eec6348508af8051b6699730890b @koichik committed Feb 11, 2013
Showing with 80 additions and 33 deletions.
  1. +7 −4 doc/api/fs.markdown
  2. +36 −15 doc/api/http.markdown
  3. +24 −8 doc/api/net.markdown
  4. +13 −6 doc/api/stream.markdown
View
11 doc/api/fs.markdown
@@ -626,7 +626,7 @@ be found in the [MDN JavaScript Reference][MDN-Date] page.
## fs.createReadStream(path, [options])
-Returns a new ReadStream object (See `Readable Stream`).
+Returns a new ReadStream object (See [Readable Stream][]).
`options` is an object with the following defaults:
@@ -655,7 +655,7 @@ An example to read the last 10 bytes of a file which is 100 bytes long:
## Class: fs.ReadStream
-`ReadStream` is a [Readable Stream](stream.html#stream_readable_stream).
+`ReadStream` is a [Readable Stream][].
### Event: 'open'
@@ -666,7 +666,7 @@ Emitted when the ReadStream's file is opened.
## fs.createWriteStream(path, [options])
-Returns a new WriteStream object (See `Writable Stream`).
+Returns a new WriteStream object (See [Writable Stream][]).
`options` is an object with the following defaults:
@@ -681,7 +681,7 @@ default mode `w`.
## fs.WriteStream
-`WriteStream` is a [Writable Stream](stream.html#stream_writable_stream).
+`WriteStream` is a [Writable Stream][].
### Event: 'open'
@@ -715,3 +715,6 @@ See more details in [fs.watch](#fs_fs_watch_filename_options_listener).
* `error` {Error object}
Emitted when an error occurs.
+
+[Readable Stream]: stream.html#stream_class_stream_readable
+[Writable Stream]: stream.html#stream_class_stream_writable
View
51 doc/api/http.markdown
@@ -733,6 +733,14 @@ respectively. It may be used to access response status, headers and data.
It implements the [Readable Stream][] interface. `http.IncomingMessage` is an
[EventEmitter][] with the following events:
+### Event: 'readable'
+
+`function () { }`
+
+When there is message body ready to be consumed. When this event emits,
+call the `read()` method to consume the data. (See [Readable Stream][]
+section for more information.)
+
### Event: 'data'
`function (chunk) { }`
@@ -741,8 +749,9 @@ Emitted when a piece of the message body is received. The chunk is a string if
an encoding has been set with `message.setEncoding()`, otherwise it's
a [Buffer][].
-Note that the __data will be lost__ if there is no listener when a
-`IncomingMessage` emits a `'data'` event.
+Note that adding a `'data'` event listener will switch the
+`http.IncomingMessage` into "old mode". (See [Compatibility][] for more
+information.)
### Event: 'end'
@@ -770,8 +779,8 @@ In case of server request, the HTTP version sent by the client. In the case of
client response, the HTTP version of the connected-to server.
Probably either `'1.1'` or `'1.0'`.
-Also `response.httpVersionMajor` is the first integer and
-`response.httpVersionMinor` is the second.
+Also `message.httpVersionMajor` is the first integer and
+`message.httpVersionMinor` is the second.
### message.headers
@@ -793,18 +802,27 @@ The request/response trailers object. Only populated after the 'end' event.
### message.setEncoding([encoding])
-Set the encoding for data emitted by the `'data'` event. See [stream.setEncoding()][] for more
-information.
+Set the encoding for data emitted by the `'data'` event. See
+[readable.setEncoding()][] for more information.
Should be set before any `'data'` events have been emitted.
+### message.read([size])
+
+Call this method to consume data once the `'readable'` event is
+emitted. (See [readable.read()][] for more information.)
+
### message.pause()
-Pauses request/response from emitting events. Useful to throttle back a download.
+Pauses request/response from emitting events. Note that calling
+`pause()` will switch the `http.IncomingMessage` into "old mode".
+(See [Compatibility][] for more information.)
### message.resume()
-Resumes a paused request/response.
+Resumes a paused request/response. Note that calling `resume()` will
+switch the `http.IncomingMessage` into "old mode". (See
+[Compatibility][] for more information.)
### message.method
@@ -824,7 +842,7 @@ present in the actual HTTP request. If the request is:
Accept: text/plain\r\n
\r\n
-Then `request.url` will be:
+Then `message.url` will be:
'/status?name=ryan'
@@ -855,10 +873,10 @@ The 3-digit HTTP response status code. E.G. `404`.
### message.socket
-The `net.Socket` object associated with the connection.
+The [net.Socket][] object associated with the connection.
-With HTTPS support, use request.connection.verifyPeer() and
-request.connection.getPeerCertificate() to obtain the client's
+With HTTPS support, use `message.socket.verifyPeer()` and
+`message.socket.getPeerCertificate()` to obtain the client's
authentication details.
@@ -873,10 +891,13 @@ authentication details.
[net.Server.close()]: net.html#net_server_close_callback
[net.Server.listen(path)]: net.html#net_server_listen_path_callback
[net.Server.listen(port)]: net.html#net_server_listen_port_host_backlog_callback
-[Readable Stream]: stream.html#stream_readable_stream
+[net.Socket]: net.html#net_class_net_socket
+[Readable Stream]: stream.html#stream_class_stream_readable
[socket.setKeepAlive()]: net.html#net_socket_setkeepalive_enable_initialdelay
[socket.setNoDelay()]: net.html#net_socket_setnodelay_nodelay
[socket.setTimeout()]: net.html#net_socket_settimeout_timeout_callback
-[stream.setEncoding()]: stream.html#stream_stream_setencoding_encoding
+[readable.setEncoding()]: stream.html#stream_readable_setencoding_encoding
[url.parse()]: url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost
-[Writable Stream]: stream.html#stream_writable_stream
+[Writable Stream]: stream.html#stream_class_stream_writable
+[Compatibility]: stream.html#stream_compatibility
+[readable.read()]: stream.html#stream_readable_read_size
View
32 doc/api/net.markdown
@@ -331,7 +331,12 @@ Users who experience large or growing `bufferSize` should attempt to
### socket.setEncoding([encoding])
Set the encoding for the socket as a Readable Stream. See
-[stream.setEncoding()][] for more information.
+[readable.setEncoding()][] for more information.
+
+### socket.read([size])
+
+Call this method to consume data once the `'readable'` event is
+emitted. (See [readable.read()][] for more information.)
### socket.write(data, [encoding], [callback])
@@ -360,12 +365,15 @@ case of errors (parse error or so).
### socket.pause()
-Pauses the reading of data. That is, `'data'` events will not be emitted.
-Useful to throttle back an upload.
+Pauses the reading of data. Note that calling `pause()` will switch
+the socket into "old mode". (See [Compatibility][] for more
+information.)
### socket.resume()
-Resumes reading after a call to `pause()`.
+Resumes reading after a call to `pause()`. Note that calling
+`resume()` will switch the socket into "old mode". (See
+[Compatibility][] for more information.)
### socket.setTimeout(timeout, [callback])
@@ -455,6 +463,12 @@ The amount of bytes sent.
Emitted when a socket connection is successfully established.
See `connect()`.
+### Event: 'readable'
+
+When there is data ready to be consumed. When this event emits, call
+the `read()` method to consume the data. (See [Readable Stream][]
+section for more information.)
+
### Event: 'data'
* {Buffer object}
@@ -463,8 +477,8 @@ Emitted when data is received. The argument `data` will be a `Buffer` or
`String`. Encoding of data is set by `socket.setEncoding()`.
(See the [Readable Stream][] section for more information.)
-Note that the __data will be lost__ if there is no listener when a `Socket`
-emits a `'data'` event.
+Note that adding a `'data'` event listener will switch the socket
+into "old mode". (See [Compatibility][] for more information.)
### Event: 'end'
@@ -525,5 +539,7 @@ Returns true if input is a version 6 IP address, otherwise returns false.
['end']: #net_event_end
[EventEmitter]: events.html#events_class_events_eventemitter
['listening']: #net_event_listening
-[Readable Stream]: stream.html#stream_readable_stream
-[stream.setEncoding()]: stream.html#stream_stream_setencoding_encoding
+[Readable Stream]: stream.html#stream_class_stream_readable
+[readable.setEncoding()]: stream.html#stream_readable_setencoding_encoding
+[Compatibility]: stream.html#stream_compatibility
+[readable.read()]: stream.html#stream_readable_read_size
View
19 doc/api/stream.markdown
@@ -130,7 +130,8 @@ your own extension classes.
### readable.push(chunk)
-* `chunk` {Buffer | null | String} Chunk of data to push into the read queue
+* `chunk` {Buffer | String | Object | null} Chunk of data to push into
+ the read queue
* return {Boolean} Whether or not more pushes should be performed
The `Readable` class works by putting data into a read queue to be
@@ -141,6 +142,10 @@ The `push()` method will explicitly insert some data into the read
queue. If it is called with `null` then it will signal the end of the
data.
+Note that the stream will become the "object mode" if the `push()` is
+called with the value other than a `Buffer`, a string, `undefined`,
+and `null`.
+
In some cases, you may be wrapping a lower-level source which has some
sort of pause/resume mechanism, and a data callback. In those cases,
you could wrap the low-level source object by doing something like
@@ -207,8 +212,9 @@ also writable, it may be possible to continue writing.
### Event: 'data'
-The `'data'` event emits either a `Buffer` (by default) or a string if
-`setEncoding()` was used.
+The `'data'` event emits either a `Buffer` (by default), a string (if
+`setEncoding()` was used), or an object (if the stream is in the
+"object mode").
Note that adding a `'data'` event listener will switch the Readable
stream into "old mode", where data is emitted as soon as it is
@@ -226,22 +232,23 @@ descriptor) has been closed. Not all streams will emit this.
### readable.setEncoding(encoding)
Makes the `'data'` event emit a string instead of a `Buffer`. `encoding`
-can be `'utf8'`, `'utf16le'` (`'ucs2'`), `'ascii'`, or `'hex'`.
+can be `'utf8'`, `'utf16le'` (`'ucs2'`), `'ascii'`, `'hex'`, or `base64`.
The encoding can also be set by specifying an `encoding` field to the
constructor.
### readable.read([size])
* `size` {Number | null} Optional number of bytes to read.
-* Return: {Buffer | String | null}
+* Return: {Buffer | String | Object | null}
Call this method to consume data once the `'readable'` event is
emitted.
The `size` argument will set a minimum number of bytes that you are
interested in. If not set, then the entire content of the internal
-buffer is returned.
+buffer is returned. Note that when the stream is in the "object mode",
+`size` arguments is ignored and it is always assumed to be 1.
If there is no data to consume, or if there are fewer bytes in the
internal buffer than the `size` argument, then `null` is returned, and

0 comments on commit b8bd249

Please sign in to comment.