Skip to content

Commit

Permalink
doc: clarify when writable.write callback is called
Browse files Browse the repository at this point in the history
The current documentation for writable.write only specifies that the
callback is called "once the data has been fully handled".  It is
ambiguous whether this means "successfully handled" and, if so,
whether the callback is called if the data can not be successfully
handled (i.e. an error occurs).

The ambiguity is not only in the documentation.  The stream class
implementations differ on this point.  stream.Writable invokes the
callback with any errors that occur during parameter checking or
during calls to _write.  However, not all classes return all errors
to _write. zlib.Zlib does pass argument and state errors to the
_write (_transform) callback, but does not pass data errors.
http.OutgoingMessage passes argument type errors and some other types
of errors, but not all.

This inconsistency is behind issue #1746 and, I suspect, other issues
in client code which passes a callback to write.

This commit takes no position on whether the callback error behavior
should changed, but simply attempts to document the current behavior
in a way that is open to changes so that users are not caught by
surprise.

PR-URL: #4810
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremy Whitlock <jwhitlock@apache.org>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
  • Loading branch information
kevinoid authored and rvagg committed Mar 16, 2016
1 parent c579507 commit eb73574
Showing 1 changed file with 3 additions and 1 deletion.
4 changes: 3 additions & 1 deletion doc/api/stream.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -710,7 +710,9 @@ Flush all data, buffered since [`stream.cork()`][] call.
* Returns: {Boolean} `true` if the data was handled completely.

This method writes some data to the underlying system, and calls the
supplied callback once the data has been fully handled.
supplied callback once the data has been fully handled. If an error
occurs, the callback may or may not be called with the error as its
first argument. To detect write errors, listen for the `'error'` event.

The return value indicates if you should continue writing right now.
If the data had to be buffered internally, then it will return
Expand Down

0 comments on commit eb73574

Please sign in to comment.