From eb735743494ece4c5c707cf0aae7d02a7108968c Mon Sep 17 00:00:00 2001 From: Kevin Locke Date: Thu, 21 Jan 2016 16:07:50 -0800 Subject: [PATCH] doc: clarify when writable.write callback is called 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: https://github.com/nodejs/node/pull/4810 Reviewed-By: James M Snell Reviewed-By: Jeremy Whitlock Reviewed-By: Benjamin Gruenbaum --- doc/api/stream.markdown | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index 085b88677ceec5..03dfd72d73381c 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -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