Usage

Define a node type

Nodes must implement IIntrusiveNode<TNode> or derive from IntrusiveNode<TNode>.

public sealed class WorkItem : IntrusiveNode<WorkItem>
{
    public int Id;
}

Each node carries its own linkage; the queue never allocates or wraps nodes.

Create a queue with a permanent sentinel

var stub = new WorkItem();
var queue = new ValueIntrusiveMpscQueue<WorkItem>(stub);

The stub node must remain alive for the entire lifetime of the queue.

Enqueue (multi-producer)

queue.Enqueue(new WorkItem { Id = 42 });

This operation is lock-free and safe to call concurrently from multiple threads.

Dequeue (single-consumer)

if (queue.TryDequeue(out var item))
{
    // process item
}

If stronger dequeue guarantees are required (for example, when a producer has advanced the tail but not yet published the link), use:

queue.TryDequeueSpin(out var item);

Correctness and constraints

This type intentionally enforces strict usage rules:

• Exactly one consumer thread is supported.
• A node must not be enqueued more than once at a time.
• Nodes may be reused only after being dequeued.
• The sentinel (stub) node must remain alive for the queue’s lifetime.
• TryDequeue may return false while a producer is mid-enqueue — this is expected.

Violating these constraints will result in undefined behavior.

This is a low-level primitive, not a general-purpose collection.

When to use this

This queue is a good fit when:

• You are building synchronization primitives (async locks, semaphores, schedulers).
• Allocation-free behavior is mandatory.
• You need tight control over memory ordering and visibility.
• You can enforce a single-consumer contract.
• You care about instruction count, cache locality, and predictable latency.

If you need a general-purpose queue with multiple consumers, prefer ConcurrentQueue<T> or System.Threading.Channels.