From 6ab271510e55aa200a91288f5c129f7f6aeb25b4 Mon Sep 17 00:00:00 2001 From: sendoru Date: Tue, 6 Aug 2024 08:36:20 +0900 Subject: [PATCH] doc: move `onread` option from `socket.connect()` to `new net.socket()` Fixes: https://github.com/nodejs/node/issues/53792 PR-URL: https://github.com/nodejs/node/pull/54194 Reviewed-By: Paolo Insogna Reviewed-By: Luigi Pinca Reviewed-By: Tim Perry --- doc/api/net.md | 66 +++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/doc/api/net.md b/doc/api/net.md index a1c8f624a50e62..1b02978cfa14fa 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -660,6 +660,19 @@ changes: `false`. * `fd` {number} If specified, wrap around an existing socket with the given file descriptor, otherwise a new socket will be created. + * `onread` {Object} If specified, incoming data is stored in a single `buffer` + and passed to the supplied `callback` when data arrives on the socket. + This will cause the streaming functionality to not provide any data. + The socket will emit events like `'error'`, `'end'`, and `'close'` + as usual. Methods like `pause()` and `resume()` will also behave as + expected. + * `buffer` {Buffer|Uint8Array|Function} Either a reusable chunk of memory to + use for storing incoming data or a function that returns such. + * `callback` {Function} This function is called for every chunk of incoming + data. Two arguments are passed to it: the number of bytes written to + `buffer` and a reference to `buffer`. Return `false` from this function to + implicitly `pause()` the socket. This function will be executed in the + global context. * `readable` {boolean} Allow reads on the socket when an `fd` is passed, otherwise ignored. **Default:** `false`. * `signal` {AbortSignal} An Abort signal that may be used to destroy the @@ -1021,39 +1034,6 @@ For [IPC][] connections, available `options` are: See [Identifying paths for IPC connections][]. If provided, the TCP-specific options above are ignored. -For both types, available `options` include: - -* `onread` {Object} If specified, incoming data is stored in a single `buffer` - and passed to the supplied `callback` when data arrives on the socket. - This will cause the streaming functionality to not provide any data. - The socket will emit events like `'error'`, `'end'`, and `'close'` - as usual. Methods like `pause()` and `resume()` will also behave as - expected. - * `buffer` {Buffer|Uint8Array|Function} Either a reusable chunk of memory to - use for storing incoming data or a function that returns such. - * `callback` {Function} This function is called for every chunk of incoming - data. Two arguments are passed to it: the number of bytes written to - `buffer` and a reference to `buffer`. Return `false` from this function to - implicitly `pause()` the socket. This function will be executed in the - global context. - -Following is an example of a client using the `onread` option: - -```js -const net = require('node:net'); -net.connect({ - port: 80, - onread: { - // Reuses a 4KiB Buffer for every read from the socket. - buffer: Buffer.alloc(4 * 1024), - callback: function(nread, buf) { - // Received data is available in `buf` from 0 to `nread`. - console.log(buf.toString('utf8', 0, nread)); - }, - }, -}); -``` - #### `socket.connect(path[, connectListener])` * `path` {string} Path the client should connect to. See @@ -1556,6 +1536,26 @@ To connect on the socket `/tmp/echo.sock`: const client = net.createConnection({ path: '/tmp/echo.sock' }); ``` +Following is an example of a client using the `port` and `onread` +option. In this case, the `onread` option will be only used to call +`new net.Socket([options])` and the `port` option will be used to +call `socket.connect(options[, connectListener])`. + +```js +const net = require('node:net'); +net.createConnection({ + port: 80, + onread: { + // Reuses a 4KiB Buffer for every read from the socket. + buffer: Buffer.alloc(4 * 1024), + callback: function(nread, buf) { + // Received data is available in `buf` from 0 to `nread`. + console.log(buf.toString('utf8', 0, nread)); + }, + }, +}); +``` + ### `net.createConnection(path[, connectListener])`