PipeOptions overrides default

[marco6]

In the description of the options available for a Pipe (from System.IO.Pipelines) I can read:

pauseWriterThreshold

The number of bytes in the Pipe before FlushAsync(CancellationToken) starts blocking. A negative value prevents FlushAsync(CancellationToken) from ever blocking, effectively making the number of bytes in the Pipe unlimited.

But this is not reflected in the code: the real behavior is an exception or a default value. Given the value is read-only, there is no way to actually set this property as depicted.

[carlossanlop]

We documented this a few weeks ago. @halter73 since you helped review these, would you mind chiming in to help clarify @marco6 's question?

I found the comment in that documentation PR where we discussed this parameter.

[halter73]

@marco6 is right, I forgot we used -1 to indicate the default PauseWriterThreshold should be used. The docs should read as follows.

pauseWriterThreshold

The number of bytes in the Pipe before FlushAsync(CancellationToken) starts blocking. A value of zero prevents FlushAsync(CancellationToken) from ever blocking, effectively making the number of bytes in the Pipe unlimited.

If you want to apply backpressure immediately, you can use a value of 1, but that probably goes without mentioning.

[carlossanlop]

I submitted a fix for this @halter73: dotnet/dotnet-api-docs#4491

Thanks for reporting @marco6

I'm reopening so it gets autoclosed when the PR is merged.