Class MessageQueue<T>

Namespace

DotCompute.Core.Messaging

Assembly

DotCompute.Core.dll

Lock-free concurrent message queue using a ring buffer for high-performance message passing.

public sealed class MessageQueue<T> : IMessageQueue<T>, IMessageQueue, IDisposable where T : IRingKernelMessage

Type Parameters

T

The message type implementing IRingKernelMessage.

Inheritance

object

MessageQueue<T>

Implements

IMessageQueue<T>

IMessageQueue

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

BufferExtensions.IsSafeToDispose(IDisposable)

BufferExtensions.SafeDispose(IDisposable)

Remarks

Uses atomic operations (Interlocked) for head/tail pointers to achieve lock-free enqueue and dequeue operations. Provides configurable backpressure strategies and optional message deduplication.

Performance: - Target: <50ns per enqueue/dequeue (lock-free path) - Zero allocations after initialization - Capacity must be a power of 2 for efficient modulo operations

Thread Safety: All operations are thread-safe and can be called concurrently from multiple threads without external synchronization.

Constructors

MessageQueue(MessageQueueOptions)

Initializes a new instance of the MessageQueue<T> class.

public MessageQueue(MessageQueueOptions options)

Parameters

options MessageQueueOptions

Configuration options for the queue.

Exceptions

ArgumentNullException

Thrown when options is null.

ArgumentOutOfRangeException

Thrown when options are invalid.

Properties

Capacity

Gets the maximum capacity of the queue.

public int Capacity { get; }

Property Value

int

Count

Gets the current number of messages in the queue.

public int Count { get; }

Property Value

int

IsEmpty

Gets a value indicating whether the queue is empty.

public bool IsEmpty { get; }

Property Value

bool

IsFull

Gets a value indicating whether the queue is full.

public bool IsFull { get; }

Property Value

bool

Methods

Clear()

Removes all messages from the queue.

public void Clear()

Dispose()

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

public void Dispose()

TryDequeue(out T?)

Attempts to dequeue a message from the queue.

public bool TryDequeue(out T? message)

Parameters

message T

When this method returns true, contains the dequeued message; otherwise, null.

Returns

bool

True if a message was successfully dequeued; false if the queue is empty.

Remarks

This is a non-blocking operation. If the queue is empty, the method returns immediately with false.

For priority queues, returns the highest priority message. For FIFO queues, returns the oldest message.

Expired messages (older than MessageTimeout) are automatically removed and not returned.

Exceptions

ObjectDisposedException

Thrown when the queue has been disposed.

TryEnqueue(T, CancellationToken)

Attempts to enqueue a message to the queue.

public bool TryEnqueue(T message, CancellationToken cancellationToken = default)

Parameters

message T

The message to enqueue.

cancellationToken CancellationToken

Cancellation token for blocking operations.

Returns

bool

True if the message was successfully enqueued; false if the queue is full and the backpressure strategy is Reject.

Remarks

Behavior depends on the configured BackpressureStrategy:

• Block: Waits until space is available (respects cancellation token)
• DropOldest: Drops oldest message and enqueues new one (returns true)
• Reject: Returns false immediately if queue is full
• DropNew: Drops new message and returns true

If deduplication is enabled, duplicate messages (same MessageId) are silently dropped and true is returned.

Exceptions

ArgumentNullException

Thrown when message is null.

OperationCanceledException

Thrown when the operation is cancelled via cancellationToken.

ObjectDisposedException

Thrown when the queue has been disposed.

TryPeek(out T?)

Attempts to peek at the next message without removing it from the queue.

public bool TryPeek(out T? message)

Parameters

message T

When this method returns true, contains the next message; otherwise, null.

Returns

bool

True if a message is available; false if the queue is empty.

Remarks

This is a non-blocking operation. The message remains in the queue after peeking and will be returned by subsequent Dequeue operations.

Thread safety: Another thread may dequeue the peeked message before you attempt to dequeue it. Use TryDequeue for atomic read-and-remove.

Exceptions

ObjectDisposedException

Thrown when the queue has been disposed.