socket.setNoDelay documentation is contradictory

[natevw]

socket.setNoDelay documentation says:

socket.setNoDelay([noDelay])

Disables the Nagle algorithm. By default TCP connections use the Nagle algorithm, they buffer data before sending it off. Setting true for noDelay will immediately fire off data each time socket.write() is called. noDelay defaults to true.

"By default TCP connections use the Nagle algorithm" … "noDelay defaults to true" — these say opposite things. Is data buffered by default (Nagle's algorithm) or is the underlying TCP_NODELAY overrided really defaulting to "on"?

[sam-github]

You are confusing whether TCP connections are using Nagle (which is _not_ called noDelay), and the (optional) argument to setNoDelay(), which is called noDelay.

• setNoDelay(true): noDelay is true, Nagle is turned off
• setNoDelay(): noDelay not specified, but since it defaults to true, Nagle is turned off
• setNoDelay(false): Nagle is turned on

[natevw]

I'm not following?

1. The documentation says socket.setNoDelay "disables the Nagle algorithm" — so I assume calling socket.setNoDelay(true) will disable the Nagle algorithm.
2. The documentation says "By default TCP connections use the Nagle algorithm" — so I assume the default is socket.setNoDelay(false)
3. The documentation says "noDelay defaults to true" — which would mean the Nagle algorithm is not used (i.e. disabled) by default.

So I assume one of my understandings up above must be false, because certainly the second statement contradicts the third, but I can't tell which you are saying is wrong.

[sam-github]

1. true
2. in effect, though in point of fact TCP sockets are created by the O/S with nagle turned off, it doesn't have to be set to that state, and node does not call setNoDelay(false)
3. false. it means exactly as I showed above: socket.setNoDelay() <--- in this call, noDelay has no value. Got it? And since noDelay has no value, what should that call do? Well, the docs say noDelay defaults to true, so that call becomes (with the default filled in) socket.setNoDelay(true)

[OrangeDog]

Maybe it should be a property instead, to avoid this confusion.
socket.noDelay = true

[natevw]

socket.setNoDelay() <--- in this call, noDelay has no value. Got it?

Ah, yes! Thank you and that makes perfect sense…in retrospect at least ;-)

[sam-github]

The API is kindof bizarre in its attempt to make undefined become true, but its hard to know how to fix the confusion.... the underlying TCP option is actually called NODELAY, so changing this to .setDelay(), with a simple boolean argument while it would look nicer from a js perspective, would confuse people who know the sockets API. Its a conundrum, but I'm glad you see how it works now.

[magicdawn]

It 's totally confusing developers. I suggest

• rename the parameter, just name it para or something else
• or leave the para, give it setNoDelay / setDelay
• or use it as a property

So just to clarify nearly 2.2 years later... is setNoDelay enabled by default or not? Because I still don't understand the documentation on it.

So, using:

socket.setNoDelay(true)

Would be correct, and turn off the nagle algorithm then, right?

[reverofevil]

Even though I see the point why it's written the way it's written, the documentation is still confusing and should be fixed.

[sam-github]

I'm sorry, I got confused between the PR changing the default and here. I like @jasnell's text above, but I would: 1. leave the argument name as nodelay, calling it `enable` leads to the interpretation that calling `.setNoDelay(enable)` with `true` enables the Nagle algorithm, when it does the opposite, it disables Nagle 2. I would change the example call in @jasnell's docs to use the `.setNoDelay()` variant, using the default, and emphasizing that the default when no argument is provided is `true` ​