From 855ff2e92c8434a2f379bec9277268f9b49596b1 Mon Sep 17 00:00:00 2001 From: Will Fuqua Date: Tue, 4 May 2021 15:11:43 +0700 Subject: [PATCH 1/3] Update docs for PipeReader.TryRead As per https://github.com/dotnet/runtime/issues/30161#issuecomment-831035626, add some documentation to `PipeReader.TryRead` to better document some unclear behavior. The unclear behavior technically resides in the `StreamPipeReader.TryRead` implementation, which is internal, so I added this as a `` to the public `PipeReader.TryRead` method instead. --- .../System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs b/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs index 165b402aa3f03..ef9ab7ad99c81 100644 --- a/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs +++ b/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs @@ -15,7 +15,9 @@ public abstract partial class PipeReader /// Attempts to synchronously read data from the . /// When this method returns , this value is set to a instance that represents the result of the read call; otherwise, this value is set to . /// if data was available, or if the call was canceled or the writer was completed; otherwise, . - /// If the pipe returns , there is no need to call . + /// If the pipe returns , there is no need to call . + /// If the current implementation is a , + /// must be called first in order to asynchronously retrieve data from the . public abstract bool TryRead(out ReadResult result); /// Asynchronously reads a sequence of bytes from the current . From 8ca456b9f748f9abb41434cc3ee11252a1dce733 Mon Sep 17 00:00:00 2001 From: Will Fuqua Date: Tue, 29 Jun 2021 20:38:43 +0700 Subject: [PATCH 2/3] remove doc reference to internal StreamPipeReader The StreamPipeReader reference is an internal type, so it should not be mentioned in the public documentation. --- .../src/System/IO/Pipelines/PipeReader.cs | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs b/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs index ef9ab7ad99c81..3a57a98de93e5 100644 --- a/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs +++ b/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs @@ -15,9 +15,15 @@ public abstract partial class PipeReader /// Attempts to synchronously read data from the . /// When this method returns , this value is set to a instance that represents the result of the read call; otherwise, this value is set to . /// if data was available, or if the call was canceled or the writer was completed; otherwise, . - /// If the pipe returns , there is no need to call . - /// If the current implementation is a , - /// must be called first in order to asynchronously retrieve data from the . + /// + /// If the pipe returns , there is no need to call . + /// + /// Note: the implementation returned by + /// will not read new data from the backing when is called. + /// must be called to read new data from the backing . + /// Any unconsumed data from a previous asynchronous read will be available to . + /// + /// public abstract bool TryRead(out ReadResult result); /// Asynchronously reads a sequence of bytes from the current . From e61099beb570dc05597e420b766df4944adee1d0 Mon Sep 17 00:00:00 2001 From: Jeff Handley Date: Fri, 8 Oct 2021 19:59:50 -0700 Subject: [PATCH 3/3] Format remarks as markdown and use !IMPORTANT --- .../src/System/IO/Pipelines/PipeReader.cs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs b/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs index cfc42fa2e68a5..5c1beb95c6b9a 100644 --- a/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs +++ b/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs @@ -15,15 +15,15 @@ public abstract partial class PipeReader /// Attempts to synchronously read data from the . /// When this method returns , this value is set to a instance that represents the result of the read call; otherwise, this value is set to . /// if data was available, or if the call was canceled or the writer was completed; otherwise, . - /// + /// , there is no need to call . - /// - /// Note: the implementation returned by - /// will not read new data from the backing when is called. - /// must be called to read new data from the backing . - /// Any unconsumed data from a previous asynchronous read will be available to . - /// - /// + /// [!IMPORTANT] + /// The `System.IO.Pipelines.PipeReader` implementation returned by `System.IO.Pipelines.PipeReader.Create(System.IO.Stream, System.IO.Pipelines.StreamPipeReaderOptions?)` + /// will not read new data from the backing `System.IO.Stream` when `System.IO.Pipelines.PipeReader.TryRead(out System.IO.Pipelines.ReadResult)` is called. + /// + /// `System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)` must be called to read new data from the backing `System.IO.Stream`. + /// Any unconsumed data from a previous asynchronous read will be available to `System.IO.Pipelines.PipeReader.TryRead(out System.IO.Pipelines.ReadResult)`. + /// ]]> public abstract bool TryRead(out ReadResult result); /// Asynchronously reads a sequence of bytes from the current .