Class MessageBrokerPushContext

Namespace

LfrlAnvil.MessageBroker.Client

Assembly

LfrlAnvil.MessageBroker.Client.dll

Represents an object that can push a single message to the server, with access to the client's internal memory pool, which allows to efficiently buffer data to be sent.

public sealed class MessageBrokerPushContext : IBufferWriter<byte>, IDisposable

Inheritance

object

MessageBrokerPushContext

Implements

IBufferWriter<byte>

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Make sure to dispose and discard an instance after pushing a message, otherwise issues like memory leaks may be encountered.

Properties

RemainingPacketLength

Returns remaining available network packet length based on currently written data and MaxNetworkMessagePacketLength (reduced by necessary packet headers).

public MemorySize RemainingPacketLength { get; }

Property Value

MemorySize

Exceptions

ObjectDisposedException

When this context has been disposed.

RemainingRoutingPacketLength

Returns remaining available routing network packet length based on currently written routing data and MaxNetworkPacketLength.

public MemorySize RemainingRoutingPacketLength { get; }

Property Value

MemorySize

Exceptions

ObjectDisposedException

When this context has been disposed.

Methods

AddTarget(int)

Adds routing target to the message in the form of a client id.

public MessageBrokerPushContext AddTarget(int clientId)

Parameters

clientId int

Id of the target client.

Returns

MessageBrokerPushContext

this.

Exceptions

ObjectDisposedException

When this context has been disposed.

ArgumentOutOfRangeException

When clientId is less than or equal to 0.

InvalidOperationException

When routing target count limit of 32767 has already been reached.

AddTarget(string)

Adds routing target to the message in the form of a client name.

public MessageBrokerPushContext AddTarget(string clientName)

Parameters

clientName string

Name of the target client.

Returns

MessageBrokerPushContext

this.

Exceptions

ObjectDisposedException

When this context has been disposed.

ArgumentOutOfRangeException

When clientName's length is less than 1 or greater than 512.

InvalidOperationException

When routing target count limit of 32767 has already been reached.

Advance(int)

Notifies the IBufferWriter<T> that count data items were written to the output Span<T> or Memory<T>.

public void Advance(int count)

Parameters

count int

The number of data items written to the Span<T> or Memory<T>.

Exceptions

ObjectDisposedException

When this context has been disposed.

Append(ReadOnlySpan<byte>)

Appends provided data to the end of the buffer.

public MessageBrokerPushContext Append(ReadOnlySpan<byte> data)

Parameters

data ReadOnlySpan<byte>

Data to append to the end of the buffer.

Returns

MessageBrokerPushContext

this.

Exceptions

ObjectDisposedException

When this context has been disposed.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

EnqueueAsync(bool)

Enqueues the buffered message for sending and returns an object capable of finalizing the process.

public ValueTask<Result<MessageBrokerPushMessageFinalizer>> EnqueueAsync(bool confirm = true)

Parameters

confirm bool

Specifies whether the server should send confirmation that it received the message. Equal to true by default.

Returns

ValueTask<Result<MessageBrokerPushMessageFinalizer>>

A task that represents the operation, which returns a Result<T> instance, with underlying MessageBrokerPushMessageFinalizer instance.

Remarks

Unexpected errors encountered during enqueueing will cause the client to be automatically disposed. Returned Result<T> will only be valid when either the message has been successfully enqueued for sending, or the publisher is already locally unbound from the channel, which will cancel the enqueueing. Make sure to always invoke returned finalizer's PushAsync() method, otherwise the client may get deadlocked and may no longer be able to send any further requests to the server!

Exceptions

ObjectDisposedException

When this context has been disposed.

MessageBrokerClientDisposedException

When client has already been disposed.

GetMemory(int)

Returns a Memory<T> to write to that is at least the requested size (specified by sizeHint).

public Memory<byte> GetMemory(int sizeHint)

Parameters

sizeHint int

The minimum length of the returned Memory<T>. If 0, a non-empty buffer is returned.

Returns

Memory<byte>

A Memory<T> of at least the size sizeHint. If sizeHint is 0, returns a non-empty buffer.

Exceptions

OutOfMemoryException

The requested buffer size is not available.

ObjectDisposedException

When this context has been disposed.

GetSpan(int)

Returns a Span<T> to write to that is at least the requested size (specified by sizeHint).

public Span<byte> GetSpan(int sizeHint)

Parameters

sizeHint int

The minimum length of the returned Span<T>. If 0, a non-empty buffer is returned.

Returns

Span<byte>

A Span<T> of at least the size sizeHint. If sizeHint is 0, returns a non-empty buffer.

Exceptions

ObjectDisposedException

When this context has been disposed.

PushAsync(bool)

Pushes the buffered message to the publisher's bound channel.

public ValueTask<Result<MessageBrokerPushResult>> PushAsync(bool confirm = true)

Parameters

confirm bool

Specifies whether the server should send confirmation that it received the message. Equal to true by default.

Returns

ValueTask<Result<MessageBrokerPushResult>>

A task that represents the operation, which returns a Result<T> instance, with underlying MessageBrokerPushResult instance.

Remarks

Unexpected errors encountered during pushing will cause the client to be automatically disposed. Returned Result<T> will only be valid when either the message has been successfully enqueued on the server side, or the publisher is already locally unbound from the channel, which will cancel the request to the server.

Exceptions

ObjectDisposedException

When this context has been disposed.

MessageBrokerClientDisposedException

When client has already been disposed.