diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index 49619a6e072..0b90be68d3f 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -43,7 +43,7 @@ Creating a typed array from a `Buffer` works with the following caveats: 2. The buffer's memory is interpreted as an array, not a byte array. That is, `new Uint32Array(new Buffer([1,2,3,4]))` creates a 4-element `Uint32Array` - with elements `[1,2,3,4]`, not an `Uint32Array` with a single element + with elements `[1,2,3,4]`, not a `Uint32Array` with a single element `[0x1020304]` or `[0x4030201]`. NOTE: Node.js v0.8 simply retained a reference to the buffer in `array.buffer` @@ -64,7 +64,9 @@ It can be constructed in a variety of ways. Allocates a new buffer of `size` octets. Note, `size` must be no more than [kMaxLength](smalloc.html#smalloc_smalloc_kmaxlength). Otherwise, a `RangeError` -will be thrown here. +will be thrown here. Unlike `ArrayBuffers`, the underlying memory for buffers +is not initialized. So the contents of a newly created `Buffer` is unknown. +Use `buf.fill(0)`to initialize a buffer to zeroes. ### new Buffer(array) diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown index 4a62c674e92..71b5b6d4025 100644 --- a/doc/api/child_process.markdown +++ b/doc/api/child_process.markdown @@ -274,7 +274,7 @@ Here is an example of sending a server: child.send('server', server); }); -And the child would the receive the server object as: +And the child would then receive the server object as: process.on('message', function(m, server) { if (m === 'server') { diff --git a/doc/api/cluster.markdown b/doc/api/cluster.markdown index f65e11c3592..129ebf2abcd 100644 --- a/doc/api/cluster.markdown +++ b/doc/api/cluster.markdown @@ -599,7 +599,7 @@ It is not emitted in the worker. ### Event: 'disconnect' -Similar to the `cluster.on('disconnect')` event, but specfic to this worker. +Similar to the `cluster.on('disconnect')` event, but specific to this worker. cluster.fork().on('disconnect', function() { // Worker has disconnected diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index 25c2f752164..73d9255ea1c 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -529,7 +529,7 @@ Example (obtaining a shared secret): ## crypto.createECDH(curve_name) -Creates a Elliptic Curve (EC) Diffie-Hellman key exchange object using a +Creates an Elliptic Curve (EC) Diffie-Hellman key exchange object using a predefined curve specified by `curve_name` string. ## Class: ECDH diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index fe42c0f68aa..e866f01eea8 100644 --- a/doc/api/dns.markdown +++ b/doc/api/dns.markdown @@ -81,7 +81,7 @@ See [supported `getaddrinfo` flags](#dns_supported_getaddrinfo_flags) below for more information on supported flags. The callback has arguments `(err, address, family)`. The `address` argument -is a string representation of a IP v4 or v6 address. The `family` argument +is a string representation of an IP v4 or v6 address. The `family` argument is either the integer 4 or 6 and denotes the family of `address` (not necessarily the value initially passed to `lookup`). @@ -155,7 +155,7 @@ attribute (e.g. `[{'priority': 10, 'exchange': 'mx.example.com'},...]`). ## dns.resolveTxt(hostname, callback) The same as `dns.resolve()`, but only for text queries (`TXT` records). -`addresses` is an 2-d array of the text records available for `hostname` (e.g., +`addresses` is a 2-d array of the text records available for `hostname` (e.g., `[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of one record. Depending on the use case, the could be either joined together or treated separately. diff --git a/doc/api/events.markdown b/doc/api/events.markdown index a98eb5ed3fd..857d5658bbd 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -104,7 +104,7 @@ Note that `emitter.setMaxListeners(n)` still has precedence over ### emitter.listeners(event) -Returns an array of listeners for the specified event. +Returns a copy of the array of listeners for the specified event. server.on('connection', function (stream) { console.log('someone connected!'); diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 4c0f9bf7e8e..3c5f6f9a091 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -775,6 +775,10 @@ on Unix systems, it never was. Returns a new ReadStream object (See `Readable Stream`). +Be aware that, unlike the default value set for `highWaterMark` on a +readable stream (16kB), the stream returned by this method has a +default value of 64kB for the same parameter. + `options` is an object with the following defaults: { flags: 'r', @@ -797,6 +801,9 @@ there's no file descriptor leak. If `autoClose` is set to true (default behavior), on `error` or `end` the file descriptor will be closed automatically. +`mode` sets the file mode (permission and sticky bits), but only if the +file was created. + An example to read the last 10 bytes of a file which is 100 bytes long: fs.createReadStream('sample.txt', {start: 90, end: 99}); @@ -820,7 +827,7 @@ Returns a new WriteStream object (See `Writable Stream`). `options` is an object with the following defaults: { flags: 'w', - encoding: null, + defaultEncoding: 'utf8', fd: null, mode: 0666 } diff --git a/doc/api/http.markdown b/doc/api/http.markdown index 3ba57a19567..7807099dec0 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -457,6 +457,7 @@ automatically parsed with [url.parse()][]. Options: +- `protocol`: Protocol to use. Defaults to `'http:'`. - `host`: A domain name or IP address of the server to issue the request to. Defaults to `'localhost'`. - `hostname`: To support `url.parse()` `hostname` is preferred over `host` @@ -897,7 +898,8 @@ is finished. ### request.abort() -Aborts a request. (New since v0.3.8.) +Marks the request as aborting. Calling this will cause remaining data +in the response to be dropped and the socket to be destroyed. ### request.setTimeout(timeout[, callback]) diff --git a/doc/api/net.markdown b/doc/api/net.markdown index f1fdf99d0e7..d00721b2101 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -90,7 +90,7 @@ Common options are: a FIN packet when the other end of the socket sends a FIN packet. Defaults to `false`. See ['end'][] event for more information. -The `connectListener` parameter will be added as an listener for the +The `connectListener` parameter will be added as a listener for the ['connect'][] event. Here is an example of a client of echo server as described previously: @@ -119,7 +119,7 @@ changed to Creates a TCP connection to `port` on `host`. If `host` is omitted, `'localhost'` will be assumed. -The `connectListener` parameter will be added as an listener for the +The `connectListener` parameter will be added as a listener for the ['connect'][] event. Is a factory method which returns a new ['net.Socket'](#net_class_net_socket). @@ -128,7 +128,7 @@ Is a factory method which returns a new ['net.Socket'](#net_class_net_socket). ## net.createConnection(path[, connectListener]) Creates unix socket connection to `path`. -The `connectListener` parameter will be added as an listener for the +The `connectListener` parameter will be added as a listener for the ['connect'][] event. A factory method which returns a new ['net.Socket'](#net_class_net_socket). @@ -150,7 +150,7 @@ parameter is 511 (not 512). This function is asynchronous. When the server has been bound, ['listening'][] event will be emitted. The last parameter `callback` -will be added as an listener for the ['listening'][] event. +will be added as a listener for the ['listening'][] event. One issue some users run into is getting `EADDRINUSE` errors. This means that another server is already running on the requested port. One way of handling this @@ -178,7 +178,7 @@ Start a local socket server listening for connections on the given `path`. This function is asynchronous. When the server has been bound, ['listening'][] event will be emitted. The last parameter `callback` -will be added as an listener for the ['listening'][] event. +will be added as a listener for the ['listening'][] event. On UNIX, the local domain is usually known as the UNIX domain. The path is a filesystem path name. It is subject to the same naming conventions and @@ -212,7 +212,7 @@ Listening on a file descriptor is not supported on Windows. This function is asynchronous. When the server has been bound, ['listening'][] event will be emitted. -the last parameter `callback` will be added as an listener for the +the last parameter `callback` will be added as a listener for the ['listening'][] event. ### server.listen(options[, callback]) @@ -374,7 +374,7 @@ This function is asynchronous. When the ['connect'][] event is emitted the socket is established. If there is a problem connecting, the `'connect'` event will not be emitted, the `'error'` event will be emitted with the exception. -The `connectListener` parameter will be added as an listener for the +The `connectListener` parameter will be added as a listener for the ['connect'][] event. diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index 52326304d9e..cc449403b60 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -164,6 +164,34 @@ readable.on('readable', function() { Once the internal buffer is drained, a `readable` event will fire again when more data is available. +The `readable` event is not emitted in the "flowing" mode with the +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: + +```javascript +var fs = require('fs'); +var rr = fs.createReadStream('foo.txt'); +rr.on('readable', function() { + console.log('readable:', rr.read()); +}); +rr.on('end', function() { + console.log('end'); +}); +``` + +The output of running this script is: + +``` +bash-3.2$ node test.js +readable: null +end +``` + #### Event: 'data' * `chunk` {Buffer | String} The chunk of data. @@ -181,6 +209,9 @@ readable.on('data', function(chunk) { console.log('got %d bytes of data', chunk.length); }); ``` +Note that the `readable` event should not be used together with `data` +because the assigning the latter switches the stream into "flowing" mode, +so the `readable` event will not be emitted. #### Event: 'end' @@ -221,7 +252,9 @@ returns it. If there is no data available, then it will return `null`. If you pass in a `size` argument, then it will return that many -bytes. If `size` bytes are not available, then it will return `null`. +bytes. If `size` bytes are not available, then it will return `null`, +unless we've ended, in which case it will return the data remaining +in the buffer. If you do not specify a `size` argument, then it will return all the data in the internal buffer. @@ -243,6 +276,9 @@ readable.on('readable', function() { 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. + #### readable.setEncoding(encoding) * `encoding` {String} The encoding to use. @@ -414,6 +450,9 @@ 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 +has been triggered; a runtime error will be raised. + If you find that you must often call `stream.unshift(chunk)` in your programs, consider implementing a [Transform][] stream instead. (See API for Stream Implementors, below.) @@ -452,6 +491,13 @@ 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. #### readable.wrap(stream) @@ -891,6 +937,10 @@ SimpleProtocol.prototype._read = function(n) { // back into the read queue so that our consumer will see it. var b = chunk.slice(split); this.unshift(b); + // calling unshift by itself does not reset the reading state + // of the stream; since we're inside _read, doing an additional + // push('') will reset the state appropriately. + this.push(''); // and let them know that we are done parsing the header. this.emit('header', this.header); @@ -930,24 +980,22 @@ initialized. * `size` {Number} Number of bytes to read asynchronously -Note: **Implement this function, but do NOT call it directly.** +Note: **Implement this method, but do NOT call it directly.** -This function should NOT be called directly. It should be implemented -by child classes, and only called by the internal Readable class -methods. +This method is prefixed with an underscore because it is internal to the +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. -All Readable stream implementations must provide a `_read` method to -fetch data from the underlying resource. - -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 -programs. However, you **are** expected to override this method in -your own extension classes. +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 data is available, put it into the read queue by calling -`readable.push(chunk)`. If `push` returns false, then you should stop -reading. When `_read` is called again, you should start pushing more -data. +Note: once the `_read()` method is called, it will not be called again until +the `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 @@ -963,19 +1011,16 @@ becomes available. There is no need, for example to "wait" until Buffer encoding, such as `'utf8'` or `'ascii'` * return {Boolean} Whether or not more pushes should be performed -Note: **This function should be called by Readable implementors, NOT +Note: **This method should be called by Readable implementors, NOT by consumers of Readable streams.** -The `_read()` function will not be called again until at least one -`push(chunk)` call is made. - -The `Readable` class works by putting data into a read queue to be -pulled out later by calling the `read()` method when the `'readable'` -event fires. +If a value other than null is passed, The `push()` method adds a chunk of data +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 `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 (EOF). +The data added with `push` can be pulled out by calling the `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 diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index dc3a0431bee..1ce524cf84f 100644 --- a/doc/api/tls.markdown +++ b/doc/api/tls.markdown @@ -694,6 +694,11 @@ This is an encrypted stream. A proxy to the underlying socket's bytesWritten accessor, this will return the total bytes written to the socket, *including the TLS overhead*. +## Class: CleartextStream + +The CleartextStream class in Node.js version v0.10.x (and prior) has been +deprecated and removed. + ## Class: tls.TLSSocket This is a wrapped version of [net.Socket][] that does transparent encryption diff --git a/doc/api/util.markdown b/doc/api/util.markdown index cc639ddb494..3765963406c 100644 --- a/doc/api/util.markdown +++ b/doc/api/util.markdown @@ -261,7 +261,7 @@ through the `constructor.super_` property. Marks that a method should not be used any more. - exports.puts = exports.deprecate(function() { + exports.puts = util.deprecate(function() { for (var i = 0, len = arguments.length; i < len; ++i) { process.stdout.write(arguments[i] + '\n'); } diff --git a/lib/_http_client.js b/lib/_http_client.js index 538586e5482..ae8e4f4e66b 100644 --- a/lib/_http_client.js +++ b/lib/_http_client.js @@ -371,7 +371,7 @@ function parserOnIncomingClient(res, shouldKeepAlive) { var req = socket._httpMessage; - // propogate "domain" setting... + // propagate "domain" setting... if (req.domain && !res.domain) { debug('setting "res.domain"'); res.domain = req.domain; @@ -474,7 +474,7 @@ function tickOnSocket(req, socket) { socket.parser = parser; socket._httpMessage = req; - // Setup "drain" propogation. + // Setup "drain" propagation. httpSocketSetup(socket); // Propagate headers limit from request object to parser diff --git a/lib/url.js b/lib/url.js index ac712318bcd..4b9ab82f93a 100644 --- a/lib/url.js +++ b/lib/url.js @@ -600,7 +600,7 @@ Url.prototype.resolveObject = function(relative) { if (psychotic) { result.hostname = result.host = srcPath.shift(); //occationaly the auth can get stuck only in host - //this especialy happens in cases like + //this especially happens in cases like //url.resolveObject('mailto:local1@domain1', 'local2@domain2') var authInHost = result.host && result.host.indexOf('@') > 0 ? result.host.split('@') : false; @@ -682,7 +682,7 @@ Url.prototype.resolveObject = function(relative) { result.hostname = result.host = isAbsolute ? '' : srcPath.length ? srcPath.shift() : ''; //occationaly the auth can get stuck only in host - //this especialy happens in cases like + //this especially happens in cases like //url.resolveObject('mailto:local1@domain1', 'local2@domain2') var authInHost = result.host && result.host.indexOf('@') > 0 ? result.host.split('@') : false; diff --git a/src/node.cc b/src/node.cc index e669706f128..1ad02e993ba 100644 --- a/src/node.cc +++ b/src/node.cc @@ -2070,7 +2070,7 @@ static void OnFatalError(const char* location, const char* message) { NO_RETURN void FatalError(const char* location, const char* message) { OnFatalError(location, message); - // to supress compiler warning + // to suppress compiler warning abort(); } diff --git a/src/node_object_wrap.h b/src/node_object_wrap.h index b604e67095e..ad6c73e4e86 100644 --- a/src/node_object_wrap.h +++ b/src/node_object_wrap.h @@ -101,7 +101,7 @@ class ObjectWrap { * attached to detached state it will be freed. Be careful not to access * the object after making this call as it might be gone! * (A "weak reference" means an object that only has a - * persistant handle.) + * persistent handle.) * * DO NOT CALL THIS FROM DESTRUCTOR */