Table of Contents

Interface IMessageQueue<T>

Namespace
DotCompute.Abstractions.Messaging
Assembly
DotCompute.Abstractions.dll

Thread-safe message queue for Ring Kernel actor communication.

public interface IMessageQueue<T> : IMessageQueue, IDisposable where T : IRingKernelMessage

Type Parameters

T

The message type implementing IRingKernelMessage.

Inherited Members
Extension Methods

Remarks

Provides lock-free or low-contention message passing between Ring Kernels with configurable backpressure, priority ordering, and deduplication.

Thread Safety: All operations are thread-safe and can be called concurrently from multiple threads. Lock-free implementations use atomic operations for optimal performance.

Usage: 

var options = new MessageQueueOptions
{
    Capacity = 2048,
    EnablePriorityQueue = true,
    BackpressureStrategy = BackpressureStrategy.DropOldest
};

using var queue = MessageQueueFactory.Create<MyMessage>(options);

// Producer
var message = new MyMessage { Value = 42 };
if (queue.TryEnqueue(message))
{
    Console.WriteLine($"Enqueued: {message.MessageId}");
}

// Consumer
if (queue.TryDequeue(out var received))
{
    Console.WriteLine($"Received: {received.Value}");
}

Methods

TryDequeue(out T?)

Attempts to dequeue a message from the queue.

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.

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.

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.

Edit this page