Stream.ReadAtLeastAsync Method

Definition

Namespace:

System.IO

Assembly:

System.Runtime.dll

Source:

Stream.cs

Asynchronously reads at least a minimum number of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.

public System.Threading.Tasks.ValueTask<int> ReadAtLeastAsync (Memory<byte> buffer, int minimumBytes, bool throwOnEndOfStream = true, System.Threading.CancellationToken cancellationToken = default);

member this.ReadAtLeastAsync : Memory<byte> * int * bool * System.Threading.CancellationToken -> System.Threading.Tasks.ValueTask<int>

Public Function ReadAtLeastAsync (buffer As Memory(Of Byte), minimumBytes As Integer, Optional throwOnEndOfStream As Boolean = true, Optional cancellationToken As CancellationToken = Nothing) As ValueTask(Of Integer)

Parameters

buffer

Memory<Byte>

The region of memory to write the data into.

minimumBytes

Int32

The minimum number of bytes to read into the buffer.

throwOnEndOfStream

Boolean

true to throw an exception if the end of the stream is reached before reading minimumBytes of bytes; false to return less than minimumBytes when the end of the stream is reached. The default is true.

cancellationToken

CancellationToken

The token to monitor for cancellation requests.

Returns

ValueTask<Int32>

A task that represents the asynchronous read operation. The value of its Result property contains the total number of bytes read into the buffer. This is guaranteed to be greater than or equal to minimumBytes when throwOnEndOfStream is true. This will be less than minimumBytes when the end of the stream is reached and throwOnEndOfStream is false. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available.

Exceptions

ArgumentOutOfRangeException

minimumBytes is negative, or is greater than the length of buffer.

EndOfStreamException

throwOnEndOfStream is true and the end of the stream is reached before reading minimumBytes bytes of data.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

Remarks

When minimumBytes is 0 (zero), this read operation will be completed without waiting for available data in the stream.