diff options
author | Vse Mozhet Byt <vsemozhetbyt@gmail.com> | 2019-09-29 16:53:43 +0300 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2019-10-02 00:35:04 +0300 |
commit | ddcd2359f4adc9fe34e793ad5c1ed33ce500eed7 (patch) | |
tree | 31f0928626233b34ef9d9ecb8516563afaa00a2c /doc/api/dgram.md | |
parent | 7ec558cb243c7ffc3a120e29dc43ed9045a8b0a0 (diff) |
doc: fix nits in dgram.md
* Make a section with a history remark a YAML section
of the relevant method.
Refs: https://github.com/nodejs/node/pull/29761#discussion_r329354848
* Make a bold line a real heading to be included in the TOC.
* Add formal return types.
* Reduce redundancy in a description.
* Unify link format.
* Fix ASCII sorting in bottom references.
PR-URL: https://github.com/nodejs/node/pull/29761
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Minwoo Jung <minwoo@nodesource.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Diffstat (limited to 'doc/api/dgram.md')
-rw-r--r-- | doc/api/dgram.md | 41 |
1 files changed, 13 insertions, 28 deletions
diff --git a/doc/api/dgram.md b/doc/api/dgram.md index ef8cc69b7d1..7d8684f7f6d 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -137,6 +137,11 @@ properties. ### socket.bind([port][, address][, callback]) <!-- YAML added: v0.1.99 +changes: + - version: v0.10 + description: The method was changed to an asynchronous execution model. + Legacy code would need to be changed to pass a callback + function to the method call. --> * `port` {integer} @@ -216,7 +221,7 @@ Specifying both a `'listening'` event listener and passing a useful. The `options` object may contain an additional `exclusive` property that is -used when using `dgram.Socket` objects with the [`cluster`] module. When +used when using `dgram.Socket` objects with the [`cluster`][] module. When `exclusive` is set to `false` (the default), cluster workers will use the same underlying socket handle allowing connection handling duties to be shared. When `exclusive` is `true`, however, the handle is not shared and attempted @@ -311,6 +316,8 @@ added: v8.7.0 added: v0.9.1 --> +* Returns: {dgram.Socket} + By default, binding a socket will cause it to block the Node.js process from exiting as long as the socket is open. The `socket.unref()` method can be used to exclude the socket from the reference counting that keeps the Node.js @@ -444,7 +451,7 @@ client.connect(41234, 'localhost', (err) => { }); ``` -**A Note about UDP datagram size** +#### Note about UDP datagram size The maximum size of an `IPv4/v6` datagram depends on the `MTU` (_Maximum Transmission Unit_) and on the `Payload Length` field size. @@ -626,6 +633,8 @@ The default on most systems is 64 but can vary. added: v0.9.1 --> +* Returns: {dgram.Socket} + By default, binding a socket will cause it to block the Node.js process from exiting as long as the socket is open. The `socket.unref()` method can be used to exclude the socket from the reference counting that keeps the Node.js @@ -637,27 +646,6 @@ Calling `socket.unref()` multiple times will have no addition effect. The `socket.unref()` method returns a reference to the socket so calls can be chained. -### Change to asynchronous `socket.bind()` behavior - -As of Node.js v0.10, [`dgram.Socket#bind()`][] changed to an asynchronous -execution model. Legacy code would use synchronous behavior: - -```js -const s = dgram.createSocket('udp4'); -s.bind(1234); -s.addMembership('224.0.0.114'); -``` - -Such legacy code would need to be changed to pass a callback function to the -[`dgram.Socket#bind()`][] function: - -```js -const s = dgram.createSocket('udp4'); -s.bind(1234, () => { - s.addMembership('224.0.0.114'); -}); -``` - ## `dgram` module functions ### dgram.createSocket(options[, callback]) @@ -708,9 +696,7 @@ added: v0.1.99 * `callback` {Function} - Attached as a listener to `'message'` events. * Returns: {dgram.Socket} -Creates a `dgram.Socket` object of the specified `type`. The `type` argument -can be either `'udp4'` or `'udp6'`. An optional `callback` function can be -passed which is added as a listener for `'message'` events. +Creates a `dgram.Socket` object of the specified `type`. Once the socket is created, calling [`socket.bind()`][] will instruct the socket to begin listening for datagram messages. When `address` and `port` are @@ -720,14 +706,13 @@ and `udp6` sockets). The bound address and port can be retrieved using [`socket.address().address`][] and [`socket.address().port`][]. [`'close'`]: #dgram_event_close -[`Error`]: errors.html#errors_class_error [`ERR_SOCKET_DGRAM_IS_CONNECTED`]: errors.html#errors_err_socket_dgram_is_connected [`ERR_SOCKET_DGRAM_NOT_CONNECTED`]: errors.html#errors_err_socket_dgram_not_connected +[`Error`]: errors.html#errors_class_error [`System Error`]: errors.html#errors_class_systemerror [`close()`]: #dgram_socket_close_callback [`cluster`]: cluster.html [`connect()`]: #dgram_socket_connect_port_address_callback -[`dgram.Socket#bind()`]: #dgram_socket_bind_options_callback [`dgram.createSocket()`]: #dgram_dgram_createsocket_options_callback [`dns.lookup()`]: dns.html#dns_dns_lookup_hostname_options_callback [`socket.address().address`]: #dgram_socket_address |