From 8c19c23e0ff00b5681fd9da6973dc146e0e826d6 Mon Sep 17 00:00:00 2001 From: Robert Nagy Date: Sat, 15 Feb 2020 14:13:29 +0100 Subject: [PATCH 1/3] doc: fix Writable.write callback description Clarifies a userland invariant until a better solution can be found. Also moves a misplaced sentence from _write to write. Refs: https://github.com/nodejs/node/pull/31756 Refs: https://github.com/nodejs/node/pull/31765 --- doc/api/stream.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index cf3ecd461c13ed..7957bb53d56b99 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -585,8 +585,8 @@ The `writable.write()` method writes some data to the stream, and calls the 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 reliably detect write errors, add a listener for the -`'error'` event. If `callback` is called with an error, it will be called -before the `'error'` event is emitted. +`'error'` event. The `callback` method will always be called asynchronously +and before `'error'` is emitted. The return value is `true` if the internal buffer is less than the `highWaterMark` configured when the stream was created after admitting `chunk`. @@ -1890,8 +1890,8 @@ methods only. The `callback` method must be called to signal either that the write completed successfully or failed with an error. The first argument passed to the `callback` must be the `Error` object if the call failed or `null` if the -write succeeded. The `callback` method will always be called asynchronously and -before `'error'` is emitted. +write succeeded. The `callback` must be called synchronously inside of +`writable._write()` or asynchronously (i.e. different tick). All calls to `writable.write()` that occur between the time `writable._write()` is called and the `callback` is called will cause the written data to be From c17d261cfb28f5b0a7ae723e090d730b6d511c8c Mon Sep 17 00:00:00 2001 From: Robert Nagy Date: Sun, 16 Feb 2020 00:02:26 +0100 Subject: [PATCH 2/3] Update doc/api/stream.md Co-Authored-By: Luigi Pinca --- doc/api/stream.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index 7957bb53d56b99..303c8d1dda48fd 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -585,7 +585,8 @@ The `writable.write()` method writes some data to the stream, and calls the 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 reliably detect write errors, add a listener for the -`'error'` event. The `callback` method will always be called asynchronously +`'error'` event. The `callback` is called asynchronously and before `'error'` is +emitted. and before `'error'` is emitted. The return value is `true` if the internal buffer is less than the From ff707a5cece251b6c979e3a80024e99c9b5e20a7 Mon Sep 17 00:00:00 2001 From: Robert Nagy Date: Sun, 16 Feb 2020 16:58:54 +0100 Subject: [PATCH 3/3] Update doc/api/stream.md Co-Authored-By: Luigi Pinca --- doc/api/stream.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index 303c8d1dda48fd..acb859f3920e5c 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -587,7 +587,6 @@ occurs, the `callback` *may or may not* be called with the error as its first argument. To reliably detect write errors, add a listener for the `'error'` event. The `callback` is called asynchronously and before `'error'` is emitted. -and before `'error'` is emitted. The return value is `true` if the internal buffer is less than the `highWaterMark` configured when the stream was created after admitting `chunk`.