Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit e76822f

Browse filesBrowse files
jasnellrvagg
jasnell
authored and
rvagg
committed
doc: multiple documentation updates cherry picked from v0.12
 * doc: improve http.abort description * doc: mention that mode is ignored if file exists * docs: Fix default options for fs.createWriteStream() * Documentation update about Buffer initialization * doc: add a note about readable in flowing mode * doc: Document http.request protocol option * doc, comments: Grammar and spelling fixes * updated documentation for fs.createReadStream * Update child_process.markdown, spelling * doc: Clarified read method with specified size argument. * docs:events clarify emitter.listener() behavior * doc: two minor stream doc improvements * doc: clarify Readable._read and Readable.push * doc: stream.unshift does not reset reading state * doc: readable event clarification * doc: additional refinement to readable event Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ben Noorduis <ben@strongloop.com> PR-URL: #2302
1 parent 0bb099f commit e76822f
Copy full SHA for e76822f

File tree

Expand file treeCollapse file tree

12 files changed

+98
-43
lines changed
Open diff view settings
Filter options
Expand file treeCollapse file tree

12 files changed

+98
-43
lines changed
Open diff view settings
Collapse file

‎doc/api/buffer.markdown‎

Copy file name to clipboardExpand all lines: doc/api/buffer.markdown
+5-1Lines changed: 5 additions & 1 deletion
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Creating a typed array from a `Buffer` works with the following caveats:
4343

4444
2. The buffer's memory is interpreted as an array, not a byte array. That is,
4545
`new Uint32Array(new Buffer([1,2,3,4]))` creates a 4-element `Uint32Array`
46-
with elements `[1,2,3,4]`, not an `Uint32Array` with a single element
46+
with elements `[1,2,3,4]`, not a `Uint32Array` with a single element
4747
`[0x1020304]` or `[0x4030201]`.
4848

4949
NOTE: Node.js v0.8 simply retained a reference to the buffer in `array.buffer`
@@ -67,6 +67,10 @@ Allocates a new buffer of `size` bytes. `size` must be less than
6767
2,147,483,648 bytes (2 GB) on 64 bits architectures,
6868
otherwise a `RangeError` is thrown.
6969

70+
Unlike `ArrayBuffers`, the underlying memory for buffers is not initialized. So
71+
the contents of a newly created `Buffer` is unknown. Use `buf.fill(0)`to
72+
initialize a buffer to zeroes.
73+
7074
### new Buffer(array)
7175

7276
* `array` Array
Collapse file

‎doc/api/child_process.markdown‎

Copy file name to clipboardExpand all lines: doc/api/child_process.markdown
+1-1Lines changed: 1 addition & 1 deletion
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -279,7 +279,7 @@ Here is an example of sending a server:
279279
child.send('server', server);
280280
});
281281

282-
And the child would the receive the server object as:
282+
And the child would then receive the server object as:
283283

284284
process.on('message', function(m, server) {
285285
if (m === 'server') {
Collapse file

‎doc/api/cluster.markdown‎

Copy file name to clipboardExpand all lines: doc/api/cluster.markdown
+2-2Lines changed: 2 additions & 2 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ values are `"rr"` and `"none"`.
121121
## cluster.settings
122122

123123
* {Object}
124-
* `execArgv` {Array} list of string arguments passed to the io.js executable.
124+
* `execArgv` {Array} list of string arguments passed to the io.js executable.
125125
(Default=`process.execArgv`)
126126
* `exec` {String} file path to worker file. (Default=`process.argv[1]`)
127127
* `args` {Array} string arguments passed to worker.
@@ -613,7 +613,7 @@ It is not emitted in the worker.
613613

614614
### Event: 'disconnect'
615615

616-
Similar to the `cluster.on('disconnect')` event, but specfic to this worker.
616+
Similar to the `cluster.on('disconnect')` event, but specific to this worker.
617617

618618
cluster.fork().on('disconnect', function() {
619619
// Worker has disconnected
Collapse file

‎doc/api/dns.markdown‎

Copy file name to clipboardExpand all lines: doc/api/dns.markdown
+2-2Lines changed: 2 additions & 2 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ All properties are optional. An example usage of options is shown below.
8585
```
8686

8787
The callback has arguments `(err, address, family)`. `address` is a string
88-
representation of a IP v4 or v6 address. `family` is either the integer 4 or 6
88+
representation of an IP v4 or v6 address. `family` is either the integer 4 or 6
8989
and denotes the family of `address` (not necessarily the value initially passed
9090
to `lookup`).
9191

@@ -163,7 +163,7 @@ attribute (e.g. `[{'priority': 10, 'exchange': 'mx.example.com'},...]`).
163163
## dns.resolveTxt(hostname, callback)
164164

165165
The same as `dns.resolve()`, but only for text queries (`TXT` records).
166-
`addresses` is an 2-d array of the text records available for `hostname` (e.g.,
166+
`addresses` is a 2-d array of the text records available for `hostname` (e.g.,
167167
`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of
168168
one record. Depending on the use case, the could be either joined together or
169169
treated separately.
Collapse file

‎doc/api/events.markdown‎

Copy file name to clipboardExpand all lines: doc/api/events.markdown
+1-1Lines changed: 1 addition & 1 deletion
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ Note that `emitter.setMaxListeners(n)` still has precedence over
122122

123123
### emitter.listeners(event)
124124

125-
Returns an array of listeners for the specified event.
125+
Returns a copy of the array of listeners for the specified event.
126126

127127
server.on('connection', function (stream) {
128128
console.log('someone connected!');
Collapse file

‎doc/api/fs.markdown‎

Copy file name to clipboardExpand all lines: doc/api/fs.markdown
+9-2Lines changed: 9 additions & 2 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -801,6 +801,10 @@ on Unix systems, it never was.
801801

802802
Returns a new ReadStream object (See `Readable Stream`).
803803

804+
Be aware that, unlike the default value set for `highWaterMark` on a
805+
readable stream (16 kb), the stream returned by this method has a
806+
default value of 64 kb for the same parameter.
807+
804808
`options` is an object or string with the following defaults:
805809

806810
{ flags: 'r',
@@ -823,6 +827,9 @@ there's no file descriptor leak. If `autoClose` is set to true (default
823827
behavior), on `error` or `end` the file descriptor will be closed
824828
automatically.
825829

830+
`mode` sets the file mode (permission and sticky bits), but only if the
831+
file was created.
832+
826833
An example to read the last 10 bytes of a file which is 100 bytes long:
827834

828835
fs.createReadStream('sample.txt', {start: 90, end: 99});
@@ -847,14 +854,14 @@ Returns a new WriteStream object (See `Writable Stream`).
847854
`options` is an object or string with the following defaults:
848855

849856
{ flags: 'w',
850-
encoding: null,
857+
defaultEncoding: 'utf8',
851858
fd: null,
852859
mode: 0o666 }
853860

854861
`options` may also include a `start` option to allow writing data at
855862
some position past the beginning of the file. Modifying a file rather
856863
than replacing it may require a `flags` mode of `r+` rather than the
857-
default mode `w`. The `encoding` can be `'utf8'`, `'ascii'`, `binary`,
864+
default mode `w`. The `defaultEncoding` can be `'utf8'`, `'ascii'`, `binary`,
858865
or `'base64'`.
859866

860867
Like `ReadStream` above, if `fd` is specified, `WriteStream` will ignore the
Collapse file

‎doc/api/http.markdown‎

Copy file name to clipboardExpand all lines: doc/api/http.markdown
+3-1Lines changed: 3 additions & 1 deletion
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -462,6 +462,7 @@ automatically parsed with [url.parse()][].
462462

463463
Options:
464464

465+
- `protocol`: Protocol to use. Defaults to `'http'`.
465466
- `host`: A domain name or IP address of the server to issue the request to.
466467
Defaults to `'localhost'`.
467468
- `hostname`: Alias for `host`. To support `url.parse()` `hostname` is
@@ -911,7 +912,8 @@ is finished.
911912

912913
### request.abort()
913914

914-
Aborts a request. (New since v0.3.8.)
915+
Marks the request as aborting. Calling this will cause remaining data
916+
in the response to be dropped and the socket to be destroyed.
915917

916918
### request.setTimeout(timeout[, callback])
917919

Collapse file

‎doc/api/stream.markdown‎

Copy file name to clipboardExpand all lines: doc/api/stream.markdown
+69-27Lines changed: 69 additions & 27 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,34 @@ readable.on('readable', function() {
164164
Once the internal buffer is drained, a `readable` event will fire
165165
again when more data is available.
166166

167+
The `readable` event is not emitted in the "flowing" mode with the
168+
sole exception of the last one, on end-of-stream.
169+
170+
The 'readable' event indicates that the stream has new information:
171+
either new data is available or the end of the stream has been reached.
172+
In the former case, `.read()` will return that data. In the latter case,
173+
`.read()` will return null. For instance, in the following example, `foo.txt`
174+
is an empty file:
175+
176+
```javascript
177+
var fs = require('fs');
178+
var rr = fs.createReadStream('foo.txt');
179+
rr.on('readable', function() {
180+
console.log('readable:', rr.read());
181+
});
182+
rr.on('end', function() {
183+
console.log('end');
184+
});
185+
```
186+
187+
The output of running this script is:
188+
189+
```
190+
bash-3.2$ node test.js
191+
readable: null
192+
end
193+
```
194+
167195
#### Event: 'data'
168196

169197
* `chunk` {Buffer | String} The chunk of data.
@@ -221,7 +249,9 @@ returns it. If there is no data available, then it will return
221249
`null`.
222250

223251
If you pass in a `size` argument, then it will return that many
224-
bytes. If `size` bytes are not available, then it will return `null`.
252+
bytes. If `size` bytes are not available, then it will return `null`,
253+
unless we've ended, in which case it will return the data remaining
254+
in the buffer.
225255

226256
If you do not specify a `size` argument, then it will return all the
227257
data in the internal buffer.
@@ -243,6 +273,9 @@ readable.on('readable', function() {
243273
If this method returns a data chunk, then it will also trigger the
244274
emission of a [`'data'` event][].
245275

276+
Note that calling `readable.read([size])` after the `end` event has been
277+
triggered will return `null`. No runtime error will be raised.
278+
246279
#### readable.setEncoding(encoding)
247280

248281
* `encoding` {String} The encoding to use.
@@ -414,6 +447,9 @@ parser, which needs to "un-consume" some data that it has
414447
optimistically pulled out of the source, so that the stream can be
415448
passed on to some other party.
416449

450+
Note that `stream.unshift(chunk)` cannot be called after the `end` event
451+
has been triggered; a runtime error will be raised.
452+
417453
If you find that you must often call `stream.unshift(chunk)` in your
418454
programs, consider implementing a [Transform][] stream instead. (See API
419455
for Stream Implementors, below.)
@@ -452,6 +488,13 @@ function parseHeader(stream, callback) {
452488
}
453489
}
454490
```
491+
Note that, unlike `stream.push(chunk)`, `stream.unshift(chunk)` will not
492+
end the reading process by resetting the internal reading state of the
493+
stream. This can cause unexpected results if `unshift` is called during a
494+
read (i.e. from within a `_read` implementation on a custom stream). Following
495+
the call to `unshift` with an immediate `stream.push('')` will reset the
496+
reading state appropriately, however it is best to simply avoid calling
497+
`unshift` while in the process of performing a read.
455498

456499
#### readable.wrap(stream)
457500

@@ -883,6 +926,10 @@ SimpleProtocol.prototype._read = function(n) {
883926
// back into the read queue so that our consumer will see it.
884927
var b = chunk.slice(split);
885928
this.unshift(b);
929+
// calling unshift by itself does not reset the reading state
930+
// of the stream; since we're inside _read, doing an additional
931+
// push('') will reset the state appropriately.
932+
this.push('');
886933

887934
// and let them know that we are done parsing the header.
888935
this.emit('header', this.header);
@@ -922,24 +969,22 @@ initialized.
922969

923970
* `size` {Number} Number of bytes to read asynchronously
924971

925-
Note: **Implement this function, but do NOT call it directly.**
972+
Note: **Implement this method, but do NOT call it directly.**
926973

927-
This function should NOT be called directly. It should be implemented
928-
by child classes, and only called by the internal Readable class
929-
methods.
974+
This method is prefixed with an underscore because it is internal to the
975+
class that defines it and should only be called by the internal Readable
976+
class methods. All Readable stream implementations must provide a _read
977+
method to fetch data from the underlying resource.
930978

931-
All Readable stream implementations must provide a `_read` method to
932-
fetch data from the underlying resource.
933-
934-
This method is prefixed with an underscore because it is internal to
935-
the class that defines it, and should not be called directly by user
936-
programs. However, you **are** expected to override this method in
937-
your own extension classes.
979+
When _read is called, if data is available from the resource, `_read` should
980+
start pushing that data into the read queue by calling `this.push(dataChunk)`.
981+
`_read` should continue reading from the resource and pushing data until push
982+
returns false, at which point it should stop reading from the resource. Only
983+
when _read is called again after it has stopped should it start reading
984+
more data from the resource and pushing that data onto the queue.
938985

939-
When data is available, put it into the read queue by calling
940-
`readable.push(chunk)`. If `push` returns false, then you should stop
941-
reading. When `_read` is called again, you should start pushing more
942-
data.
986+
Note: once the `_read()` method is called, it will not be called again until
987+
the `push` method is called.
943988

944989
The `size` argument is advisory. Implementations where a "read" is a
945990
single call that returns data can use this to know how much data to
@@ -955,19 +1000,16 @@ becomes available. There is no need, for example to "wait" until
9551000
Buffer encoding, such as `'utf8'` or `'ascii'`
9561001
* return {Boolean} Whether or not more pushes should be performed
9571002

958-
Note: **This function should be called by Readable implementors, NOT
1003+
Note: **This method should be called by Readable implementors, NOT
9591004
by consumers of Readable streams.**
9601005

961-
The `_read()` function will not be called again until at least one
962-
`push(chunk)` call is made.
963-
964-
The `Readable` class works by putting data into a read queue to be
965-
pulled out later by calling the `read()` method when the `'readable'`
966-
event fires.
1006+
If a value other than null is passed, The `push()` method adds a chunk of data
1007+
into the queue for subsequent stream processors to consume. If `null` is
1008+
passed, it signals the end of the stream (EOF), after which no more data
1009+
can be written.
9671010

968-
The `push()` method will explicitly insert some data into the read
969-
queue. If it is called with `null` then it will signal the end of the
970-
data (EOF).
1011+
The data added with `push` can be pulled out by calling the `read()` method
1012+
when the `'readable'`event fires.
9711013

9721014
This API is designed to be as flexible as possible. For example,
9731015
you may be wrapping a lower-level source which has some sort of
@@ -1315,7 +1357,7 @@ for examples and testing, but there are occasionally use cases where
13151357
it can come in handy as a building block for novel sorts of streams.
13161358

13171359

1318-
## Simplified Constructor API
1360+
## Simplified Constructor API
13191361

13201362
<!--type=misc-->
13211363

Collapse file

‎lib/_http_client.js‎

Copy file name to clipboardExpand all lines: lib/_http_client.js
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -359,7 +359,7 @@ function parserOnIncomingClient(res, shouldKeepAlive) {
359359
var req = socket._httpMessage;
360360

361361

362-
// propogate "domain" setting...
362+
// propagate "domain" setting...
363363
if (req.domain && !res.domain) {
364364
debug('setting "res.domain"');
365365
res.domain = req.domain;
@@ -465,7 +465,7 @@ function tickOnSocket(req, socket) {
465465
socket.parser = parser;
466466
socket._httpMessage = req;
467467

468-
// Setup "drain" propogation.
468+
// Setup "drain" propagation.
469469
httpSocketSetup(socket);
470470

471471
// Propagate headers limit from request object to parser
Collapse file

‎lib/url.js‎

Copy file name to clipboardExpand all lines: lib/url.js
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -587,7 +587,7 @@ Url.prototype.resolveObject = function(relative) {
587587
if (psychotic) {
588588
result.hostname = result.host = srcPath.shift();
589589
//occationaly the auth can get stuck only in host
590-
//this especialy happens in cases like
590+
//this especially happens in cases like
591591
//url.resolveObject('mailto:local1@domain1', 'local2@domain2')
592592
var authInHost = result.host && result.host.indexOf('@') > 0 ?
593593
result.host.split('@') : false;
@@ -669,7 +669,7 @@ Url.prototype.resolveObject = function(relative) {
669669
result.hostname = result.host = isAbsolute ? '' :
670670
srcPath.length ? srcPath.shift() : '';
671671
//occationaly the auth can get stuck only in host
672-
//this especialy happens in cases like
672+
//this especially happens in cases like
673673
//url.resolveObject('mailto:local1@domain1', 'local2@domain2')
674674
var authInHost = result.host && result.host.indexOf('@') > 0 ?
675675
result.host.split('@') : false;

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.