Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix doc net connection #54194

Merged
merged 4 commits into from
Aug 5, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 33 additions & 33 deletions doc/api/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -667,6 +667,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
Expand Down Expand Up @@ -1038,39 +1051,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
Expand Down Expand Up @@ -1573,6 +1553,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])`

<!-- YAML
Expand Down
Loading