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

object

MessagePackAsyncReader

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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

pipeReader PipeReader

The 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.

Methods

AdvanceTo(SequencePosition)

Follows up on a prior call to ReadNextStructureAsync(SerializationContext, CancellationToken) to report some subset of the sequence as consumed.

public void AdvanceTo(SequencePosition consumed)

Parameters

consumed SequencePosition

The position that was consumed. Should be End on the value returned from ReadNextStructureAsync(SerializationContext, CancellationToken) if the whole sequence was deserialize.

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.

AdvanceTo(SequencePosition, SequencePosition)

Follows up on a prior call to ReadNextStructureAsync(SerializationContext, CancellationToken) to report some subset of the sequence as consumed.

public void AdvanceTo(SequencePosition consumed, SequencePosition examined)

Parameters

consumed SequencePosition

The position that was consumed. Should be End on the value returned from ReadNextStructureAsync(SerializationContext, CancellationToken) if the whole sequence was deserialize.

examined SequencePosition

The position that was examined up to. Should always be no earlier in the sequence than consumed.

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.

BufferNextStructureAsync(SerializationContext, CancellationToken)

Retrieves enough data from the pipe to read the next msgpack structure.

public ValueTask BufferNextStructureAsync(SerializationContext context, CancellationToken cancellationToken)

Parameters

context SerializationContext

The serialization context.

cancellationToken CancellationToken

A cancellation tokne.

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.

ReadArrayHeaderAsync(CancellationToken)

Read an array header from Array16, Array32, or some built-in code between MinFixArray and MaxFixArray.

public ValueTask<int> ReadArrayHeaderAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<int>

The number of elements in the array.

Exceptions

EndOfStreamException

Thrown if the header cannot be read in the bytes left in the Sequence or if it is clear that there are insufficient bytes remaining after the header to include all the elements the header claims to be there.

MessagePackSerializationException

Thrown if a code other than an array header is encountered.

ReadMapHeaderAsync(CancellationToken)

Read a map header from Map16, Map32, or some built-in code between MinFixMap and MaxFixMap.

public ValueTask<int> ReadMapHeaderAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<int>

The number of key=value pairs in the map.

Exceptions

EndOfStreamException

Thrown if the header cannot be read in the bytes left in the Sequence or if it is clear that there are insufficient bytes remaining after the header to include all the elements the header claims to be there.

MessagePackSerializationException

Thrown if a code other than an map header is encountered.

ReadNextStructureAsync(SerializationContext, CancellationToken)

Retrieves enough data from the pipe to read the next msgpack structure.

public ValueTask<ReadOnlySequence<byte>> ReadNextStructureAsync(SerializationContext context, CancellationToken cancellationToken)

Parameters

context SerializationContext

The serialization context.

cancellationToken CancellationToken

A cancellation tokne.

Returns

ValueTask<ReadOnlySequence<byte>>

The buffer containing exactly the next structure.

Remarks

After a successful call to this method, the caller must call AdvanceTo(SequencePosition, SequencePosition), usually with End to indicate that the next msgpack structure has been consumed. After that call, the caller must not read the buffer again as it will have been recycled.

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.

ReadNextStructuresAsync(int, SerializationContext, CancellationToken)

Gets the fully-capable, synchronous reader.

public ValueTask<ReadOnlySequence<byte>> ReadNextStructuresAsync(int minimumDesiredBufferedStructures, SerializationContext context, CancellationToken cancellationToken)

Parameters

minimumDesiredBufferedStructures int

The number of top-level structures expected by the caller that must be included in the returned buffer.

context SerializationContext

The serialization context.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<ReadOnlySequence<byte>>

The buffer, for use in creating a MessagePackReader. This buffer may be larger than needed to include minimumDesiredBufferedStructures.

Remarks

The caller must take care to call AdvanceTo(SequencePosition) with Position before any other methods on this class after this call.

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.

ReadNextStructuresAsync(int, int, SerializationContext, CancellationToken)

Gets the fully-capable, synchronous reader.

public ValueTask<(ReadOnlySequence<byte> Buffer, int IncludedStructures)> ReadNextStructuresAsync(int minimumDesiredBufferedStructures, int countUpTo, SerializationContext context, CancellationToken cancellationToken)

Parameters

minimumDesiredBufferedStructures int

The number of top-level structures expected by the caller that must be included in the returned buffer.

countUpTo int

The number of top-level structures to count and report on in the result.

context SerializationContext

The serialization context.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<(ReadOnlySequence<byte> Buffer, int IncludedStructures)>

The buffer, for use in creating a MessagePackReader, which will contain at least minimumDesiredBufferedStructures top-level structures and may include more. Also returns the number of top-level structures included in the buffer that were counted (up to countUpTo).

Remarks

The caller must take care to call AdvanceTo(SequencePosition) with Position before any other methods on this class after this call.

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.

SkipAsync(SerializationContext, CancellationToken)

Skips the next msgpack structure in the pipe.

public ValueTask SkipAsync(SerializationContext context, CancellationToken cancellationToken)

Parameters

context SerializationContext

The serialization context.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that completes when done reading past the next msgpack structure.

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.

TryReadNilAsync(CancellationToken)

Reads nil if it is the next token.

public ValueTask<bool> TryReadNilAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<bool>

true if the next token was nil; false otherwise.

Exceptions

EndOfStreamException

Thrown if the end of the sequence provided to the constructor is reached before the expected end of the data.