Doc: stream becomes paused after unpipe.

[iliakan]

Fixed the docs.
isPaused does not require explicit pause call in fact.

[jasnell]

LGTM

[silverwind]

Please wrap the lines at 80 chars.

[jasnell]

@chrisdickinson

[jasnell]

@nodejs/documentation ... can we please get some additional review on this one?
@iliakan ... can you rebase and update this?

[eljefedelrodeodeljefe]

LGTM pending wrapping at 80 chars

[iliakan]

did it

[addaleax]

nit: Trailing whitespace.

[addaleax]

LGTM with a nit.

@iliakan It would be cool if you could rebase this, and ideally pick a commit message more with more resemblance to the PR title here. We can do that for you on landing if you prefer, though.

Also, these edits appears to have been made from the Github editor and have an @users.noreply.github.com email address set in the Author: field. Is that intentional? If you want to have it changed, you can do that when rebasing, or have us do it on landing, too.

[addaleax]

This would also fix #4812, I think.

[iliakan]

Actually, there are 3 state of the stream right now.
The docs do not say the truth:

1. flowing
2. paused
3. explicitly paused :/

[addaleax]

I think it would be awesome if you could update this PR with that information? And probably good to ping @nodejs/streams

[mcollina]

all 'data' event handlers? Please check.

[mcollina]

@iliakan I think the states are 3, but not the one you said:

1. flowing
2. not flowing
3. explicitly paused (implies not flowing)

According to:
https://github.com/nodejs/node/blob/master/lib/_stream_readable.js#L139-L141

isPaused() means "not flowing".

[Trott]

This looks like it stalled awfully close to being land-able. @iliakan: Any chance you can rebase against master and pick this up again? (Or did this information end up in the docs already via a different pull request?)

[iliakan]

The doc was rewritten since then, maybe it still needs adjusting.

Because we have (citing):

"The Readable can switch back to paused mode using one of the following:... If there are pipe destinations, by removing any 'data' event handlers
...
Note: For backwards compatibility reasons, removing 'data' event handlers will not automatically pause the stream."

These statements contradict to each other, what you think? It's really unclear what's going on.

[Trott]

These statements contradict to each other, what you think? It's really unclear what's going on.

Re-pinging @nodejs/streams for comment.

[mcollina]

The two full sentences are:

If there are pipe destinations, by removing any 'data' event handlers, and removing all pipe destinations by calling the stream.unpipe() method.

and

For backwards compatibility reasons, removing 'data' event handlers will not automatically pause the stream. Also, if there are piped destinations, then calling stream.pause() will not guarantee that the stream will remain paused once those destinations drain and ask for more data.

If a stream is flowing, there are three situations:

a. there is a 'data' event handler
b. there are are piped destinations
c. there are multiple 'data' event handlers and piped destinations

To pause a stream:

a. call pause()
b. call unpipe()
c. remove all 'data' handlers, and unpipe().

We probably need to add some unit tests to cover all this cases anyway, if they are missing.

[jasnell]

@iliakan @mcollina ... ping. What's the status on this?

[mcollina]

@jasnell it's stalled. Maybe someone else should take over.

[mcollina]

@jasnell on second thoughts, I think this was fixed long ago in #6947. I think we can close this.