dotnet / dotnet/dotnet-api-docs

Extend documentation of PipeReader.AdvanceTo

Open
#4,543 1 comment 0 reactions 0 assignees View on GitHub
area-System.IO.Pipelines Pri3 untriaged
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

I started discussion on extension of documentation of PipeReader.AdvanceTo in dotnet/runtime#38277.

For the overloads
1. AdvanceTo(SequencePosition)
2. AdvanceTo(SequencePosition, SequencePosition)

I would like to change as follows:

* Remarks for both overloads
* The processing of the buffer distinguishes between consumed and examined. Consumed data can be released. The amount of examined data communicates to the pipeline when it should signal more data is available.
* The memory for the consumed data will be released and no longer available. So, the buffer previously returned from ReadAsync(CancellationToken) must not be accessed after this call.
* Additional remarks for the overload (1)
* The specified position marks the end of the buffer section which is consumed and examined. Remaining buffer is kept and immediately provided as unexamined at the next call to ReadAsync.
* Additional remarks for the overload (2)
* The specified positions mark the first buffer section to be consumed and the second buffer section to be examined. The examined position must be greater or equal to the consumed position. The buffer not yet consumed is kept.
* Specifying a buffer section to be not yet examined causes the next call to ReadAsync to return immediately the whole remaining buffer. If all data has been examined, the end position of current buffer should be specified.
* Summary of the overload (2)
* Moves forward the pipeline's read cursor to after the consumed data, marking the data as processed and examined.

Would you accept such an PR even the documentation has been improved already by #4311?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.