UDP/Datagram Sockets documentation

[dsinecos]

Module
UDP/ Datagram Sockets documentation

Current Documentation

The description for the listening event for dgram.Socket states that 'This occurs as soon as UDP sockets are created'. Reference

Expected Documentation

To my understanding this is incorrect as the listening event is fired once the socket is bound to a Port and Address. This is also stated elsewhere in the documentation (Refer) 'Once binding is complete, a 'listening' event is emitted ...'

[bnoordhuis]

I agree the wording is kind of confusing, even if it's technically correct.

"As UDP sockets are created" refers to the underlying OS socket. They're addressable the moment they're created but Node.js delays creating them until the first send() or bind(). To illustrate:

const dgram = require('dgram')
const s = dgram.createSocket('udp4')
//console.log(s.address())  // would fail with "getsockname EINVAL", no socket yet
s.on('listening', () => console.log(s.address())
s.send('', 12345, () => console.log('done'))
// Prints:
//   { address: '0.0.0.0', family: 'IPv4', port: <random port> }
//   done 

[dsinecos]

Thanks @bnoordhuis :)
This cleared up my confusion.

Borrowing from your explanation I think the existing description could be modified to something like the following -

" The listening event is emitted on the first invocation of either send() or bind() for the respective socket.

While the sockets are addressable immediately after creation using dgram.createSocket NodeJS delays creating the underlying OS socket until the first send() or bind() call is made for the respective socket.

The listening event is emitted when the underlying OS socket is created (ie on the first invocation of either send() or bind()) "

[bnoordhuis]

Yes, sounds good. Maybe even cut it short by a few more words. Want to open a PR?

[dsinecos]

Yup, I'll edit it and open a PR

Edit: Submitted a PR here - #23959

[tjconcept]

I believe this issue should be closed as #32581 landed.