Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document System.IO.Pipelines.PipeOptions #3494

Merged
merged 4 commits into from
Nov 19, 2019
Merged

Document System.IO.Pipelines.PipeOptions #3494

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
53f4ca6
Document System.IO.Pipelines.PipeOptions
carlossanlop Nov 14, 2019
1641df9
suggestions by halter73 and mairaw
carlossanlop Nov 15, 2019
dd22e8e
suggestions by halter73
carlossanlop Nov 15, 2019
53097bc
instance -> object
mairaw Nov 19, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions xml/System.IO.Pipelines/PipeOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,14 +45,14 @@
<Parameter Name="useSynchronizationContext" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="pool">To be added.</param>
<param name="readerScheduler">To be added.</param>
<param name="writerScheduler">To be added.</param>
<param name="pauseWriterThreshold">To be added.</param>
<param name="resumeWriterThreshold">To be added.</param>
<param name="minimumSegmentSize">To be added.</param>
<param name="useSynchronizationContext">To be added.</param>
<summary>Creates a new instance of <see cref="T:System.IO.Pipelines.PipeOptions" />.</summary>
<param name="pool">The pool of memory blocks to be used for buffer management.</param>
<param name="readerScheduler">The <see cref="T:System.IO.Pipelines.PipeScheduler" /> to be used to execute <see cref="T:System.IO.Pipelines.PipeReader" /> callbacks and async continuations.</param>
<param name="writerScheduler">The <see cref="T:System.IO.Pipelines.PipeScheduler" /> used to execute <see cref="T:System.IO.Pipelines.PipeWriter" /> callbacks and async continuations.</param>
<param name="pauseWriterThreshold">The number of bytes in the <see cref="T:System.IO.Pipelines.Pipe" /> before <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> starts blocking. A negative value prevents <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> from ever blocking, effectively making the number of bytes in the <see cref="T:System.IO.Pipelines.Pipe" /> unlimited.</param>
<param name="resumeWriterThreshold">The number of bytes in the <see cref="T:System.IO.Pipelines.Pipe" /> when <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> stops blocking.</param>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@halter73 you wrote:

Personally, I would use "async continuations" instead of "callbacks" everywhere "callbacks" are referenced. I would also make sure everywhere thresholds are referenced, we communicate that setting them to a negative value disables them.

But I'm not entirely sure how to explain it for resumeWriterThreshold. Would you mind helping here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is a little weird because technically you don't need to disable resumeWriterThreshold if you've already disabled the pauseWriterThreshold. And if the pauseWriterThreshold isn't disabled, it would be silly to disable the resumeWriterThreshold. So keeping this as-is and not mentioning what happens when you set the resumeWriterThreshold negative is probably fine.

<param name="minimumSegmentSize">The minimum size of the segment requested from <paramref name="pool" />.</param>
<param name="useSynchronizationContext"><see langword="true" /> if asynchronous continuations should be executed on the <see cref="T:System.Threading.SynchronizationContext" /> they were captured on; <see langword="false" /> otherwise. This takes precedence over the schedulers specified in <see cref="P:System.IO.Pipelines.PipeOptions.ReaderScheduler" /> and <see cref="P:System.IO.Pipelines.PipeOptions.WriterScheduler" />.</param>
<summary>Initializes a new instance of the <see cref="T:System.IO.Pipelines.PipeOptions" /> class with the specified parameters.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -75,7 +75,7 @@
</ReturnValue>
<Docs>
<summary>Gets the default instance of <see cref="T:System.IO.Pipelines.PipeOptions" />.</summary>
<value>To be added.</value>
<value>A <see cref="T:System.IO.Pipelines.PipeOptions" /> instance initialized with default parameters.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -97,8 +97,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the minimum size of the segment requested from <see cref="P:System.IO.Pipelines.PipeOptions.Pool" />.</summary>
<value>To be added.</value>
<summary>Gets the minimum size of the segment requested from the <see cref="P:System.IO.Pipelines.PipeOptions.Pool" />.</summary>
<value>The minimum size of the segment requested from the <see cref="P:System.IO.Pipelines.PipeOptions.Pool" />.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -120,8 +120,8 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the amount of bytes in <see cref="T:System.IO.Pipelines.Pipe" /> when <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> starts blocking.</summary>
<value>To be added.</value>
<summary>Gets the number of bytes in the <see cref="T:System.IO.Pipelines.Pipe" /> when <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> starts blocking.</summary>
<value>The number of bytes in the <see cref="T:System.IO.Pipelines.Pipe" /> when <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> starts blocking.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -143,8 +143,8 @@
<ReturnType>System.Buffers.MemoryPool&lt;System.Byte&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the <see cref="T:System.Buffers.MemoryPool`1" /> instances used for buffer management.</summary>
<value>To be added.</value>
<summary>Gets the <see cref="T:System.Buffers.MemoryPool`1" /> object used for buffer management.</summary>
<value>A pool of memory blocks used for buffer management.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -167,7 +167,7 @@
</ReturnValue>
<Docs>
<summary>Gets the <see cref="T:System.IO.Pipelines.PipeScheduler" /> used to execute <see cref="T:System.IO.Pipelines.PipeReader" /> callbacks.</summary>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<value>To be added.</value>
<value>A <see cref="T:System.IO.Pipelines.PipeScheduler" /> that is used to execute <see cref="T:System.IO.Pipelines.PipeReader" /> callbacks.</value>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -189,8 +189,8 @@
<ReturnType>System.Int64</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets amount of bytes in <see cref="T:System.IO.Pipelines.Pipe" /> when <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> stops blocking.</summary>
<value>To be added.</value>
<summary>Gets the number of bytes in the <see cref="T:System.IO.Pipelines.Pipe" /> when <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> stops blocking.</summary>
<value>The number of bytes in the <see cref="T:System.IO.Pipelines.Pipe" /> when <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> stops blocking.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -213,7 +213,7 @@
</ReturnValue>
<Docs>
<summary>Gets a value that determines if asynchronous callbacks should be executed on the <see cref="T:System.Threading.SynchronizationContext" /> they were captured on. This takes precedence over the schedulers specified in <see cref="P:System.IO.Pipelines.PipeOptions.ReaderScheduler" /> and <see cref="P:System.IO.Pipelines.PipeOptions.WriterScheduler" />.</summary>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<value>To be added.</value>
<value><see langword="true" /> if asynchronous callbacks should be executed on the <see cref="T:System.Threading.SynchronizationContext" /> they were captured on; otherwise, <see langword="false" />.</value>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -236,7 +236,7 @@
</ReturnValue>
<Docs>
<summary>Gets the <see cref="T:System.IO.Pipelines.PipeScheduler" /> used to execute <see cref="T:System.IO.Pipelines.PipeWriter" /> callbacks.</summary>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<value>To be added.</value>
<value>A <see cref="T:System.IO.Pipelines.PipeScheduler" /> object used to execute <see cref="T:System.IO.Pipelines.PipeWriter" /> callbacks.</value>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down