Class MessagePackAsyncReader
- Namespace
- Nerdbank.MessagePack
- Assembly
- Nerdbank.MessagePack.dll
A primitive types reader for the MessagePack format that reads from a PipeReader.
public class MessagePackAsyncReader- Inheritance
-
MessagePackAsyncReader
- Inherited Members
Remarks
This is an async capable and slower alternative to MessagePackReader with fewer methods, making the sync version more generally useful. It is useful when implementing the async virtual methods on MessagePackConverter<T>.
The MessagePack spec..Constructors
MessagePackAsyncReader(PipeReader)
A primitive types reader for the MessagePack format that reads from a PipeReader.
public MessagePackAsyncReader(PipeReader pipeReader)Parameters
pipeReaderPipeReaderThe pipe reader to decode from.
Remarks
This is an async capable and slower alternative to MessagePackReader with fewer methods, making the sync version more generally useful. It is useful when implementing the async virtual methods on MessagePackConverter<T>.
The MessagePack spec..Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
Properties
CancellationToken
Gets a cancellation token to consider for calls into this object.
public required CancellationToken CancellationToken { get; init; }Property Value
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
Methods
BufferNextStructureAsync(SerializationContext)
Retrieves enough data from the pipe to read the next msgpack structure.
public ValueTask BufferNextStructureAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
- ValueTask
A task that completes when enough bytes have been retrieved into local buffers.
Remarks
After awaiting this method, the next msgpack structure can be retrieved by a call to ReadAsync(CancellationToken).
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
BufferNextStructuresAsync(int, int, SerializationContext)
Gets the fully-capable, synchronous reader.
public ValueTask<int> BufferNextStructuresAsync(int minimumDesiredBufferedStructures, int countUpTo, SerializationContext context)Parameters
minimumDesiredBufferedStructuresintThe number of top-level structures expected by the caller that must be included in the returned buffer.
countUpTointThe number of top-level structures to count and report on in the result.
contextSerializationContextThe serialization context.
Returns
- ValueTask<int>
The buffer, for use in creating a MessagePackReader, which will contain at least
minimumDesiredBufferedStructurestop-level structures and may include more. Also returns the number of top-level structures included in the buffer that were counted (up tocountUpTo).
Exceptions
- OperationCanceledException
Thrown if CancellationToken is canceled or ReadAsync(CancellationToken) returns a result where IsCanceled is true.
- EndOfStreamException
Thrown if ReadAsync(CancellationToken) returns a result where IsCompleted is true and yet the buffer is not sufficient to satisfy
minimumDesiredBufferedStructures.
CreateBufferedReader()
Retrieves a MessagePackReader, which is suitable for decoding msgpack from a buffer that is known to have enough bytes for the decoding.
public MessagePackReader CreateBufferedReader()Returns
Remarks
The result must be returned with ReturnReader(ref MessagePackReader) before using this MessagePackAsyncReader again.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
CreateStreamingReader()
Retrieves a MessagePackStreamingReader, which is suitable for decoding msgpack from a buffer without throwing any exceptions, even if the buffer is incomplete.
public MessagePackStreamingReader CreateStreamingReader()Returns
Remarks
The result must be returned with ReturnReader(ref MessagePackStreamingReader) before using this MessagePackAsyncReader again.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadAsync()
Fills the buffer with msgpack bytes to decode. If the buffer already has bytes, more will be retrieved and added.
public ValueTask ReadAsync()Returns
- ValueTask
An async task.
Exceptions
- OperationCanceledException
Thrown if CancellationToken is canceled.
ReturnReader(ref MessagePackReader)
Returns a previously obtained reader when the caller is done using it, and applies the given reader's position to this reader so that future reads move continuously forward in the msgpack stream.
public void ReturnReader(ref MessagePackReader reader)Parameters
readerMessagePackReaderThe reader to return.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReturnReader(ref MessagePackStreamingReader)
Returns a previously obtained reader when the caller is done using it, and applies the given reader's position to this reader so that future reads move continuously forward in the msgpack stream.
public void ReturnReader(ref MessagePackStreamingReader reader)Parameters
readerMessagePackStreamingReaderThe reader to return.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.