Does net.Socket write() method always fire callback in next tick of even loop?

[ORESoftware]

Say we create a new socket connection:

const s = net.createConnection({port});

and we call write:

s.write('foo\n', () => {
   // does this callback always fire in the next tick of the event loop?
});

I am wondering if the "success" callback always fires in the next tick of the event loop? Wondering if it's always async, I would assume so, but no 100% sure. I am also wondering why there is never an error passed to the callback? Looks like the API for the callback has no arguments.

[addaleax]

The callback can be called later, if data has queued up and can’t be sent yet. So, if you write a lot of data in a close loop without waiting for the callback first, this can definitely occur. (Windows buffers a lot more data internally than other OS do, so it will take longer for this to happen then, at the cost of increased memory usage.)

I think the callback can be called with an error if a write failed, but I’m not sure how often that happens – most of the time, a broken socket would lead to a regular 'error' first.

[ORESoftware]

yeah, to be sure I have just used this:

s.write('foo\n', () => {
   process.nextTick(cb);
});

instead of

s.write('foo\n', cb);

[addaleax]

Oh – sorry, I think I might have misunderstood. The callback can be called later than the next tick of the event loop, but it will never be called synchronously (similar to setImmediate()).

[ORESoftware]

Got it, yeah the OP was just about whether it always fires asynchronously, sounds like that is the case, thanks. Obviously not every callback in Node.js core fires asynchronously, sometimes synchronously, such as in the streams API. I would be cool to mark functions in the docs with 3 different types:

1. always sync
2. sometimes sync sometimes async
3. always aysnc

that would be a nice way to improve callback API docs

[addaleax]

@ORESoftware Just fyi, the 2. option is almost never used (the only exception is the inspector module) – it’s usually too hard to get right for users. Most of our callbacks are always-async, so I guess it might make sense to mark the other two types?

[ORESoftware]

@addaleax as I was saying the steam API definitely has a mixture, for example on 'data' callbacks etc, event emitters in general are mixture. the socket.write() callback is a great example of an ambiguous one, is it 1, 2 or 3?