Class AsyncQueue<T>

Namespace

Microsoft.VisualStudio.Threading

Assembly

Microsoft.VisualStudio.Threading.dll

A thread-safe, asynchronously dequeuable queue.

public class AsyncQueue<T>

Type Parameters

T

The type of values kept by the queue.

Inheritance

object

AsyncQueue<T>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

AsyncQueue()

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

public AsyncQueue()

Properties

Completion

Gets a task that transitions to a completed state when Complete() is called and the queue is empty.

public Task Completion { get; }

Property Value

Task

Count

Gets the number of elements currently in the queue.

public int Count { get; }

Property Value

int

InitialCapacity

Gets the initial capacity for the queue.

protected virtual int InitialCapacity { get; }

Property Value

int

IsCompleted

Gets a value indicating whether the queue is both empty and had Complete() invoked.

public bool IsCompleted { get; }

Property Value

bool

Remarks

This is arguably redundant with Completion.IsCompleted, but this property won't cause the lazy instantiation of the Task that Completion may if there is no other reason for the Task to exist.

IsEmpty

Gets a value indicating whether the queue is currently empty.

public bool IsEmpty { get; }

Property Value

bool

SyncRoot

Gets the synchronization object used by this queue.

protected object SyncRoot { get; }

Property Value

object

Methods

Complete()

Signals that no further elements will be enqueued.

public void Complete()

Remarks

This method will return immediately. Elements enqueued before calling this method may still be dequeued. IsCompleted will return true only after this method has been called and the queue is empty.

DequeueAsync(CancellationToken)

Gets a task whose result is the element at the head of the queue.

public Task<T> DequeueAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token whose cancellation signals lost interest in the item. Cancelling this token does not guarantee that the task will be canceled before it is assigned a resulting element from the head of the queue. It is the responsibility of the caller to ensure after cancellation that either the task is canceled, or it has a result which the caller is responsible for then handling.

Returns

Task<T>

A task whose result is the head element.

Exceptions

OperationCanceledException

Thrown when this instance has an empty queue and Complete() has been called. Also thrown when cancellationToken is canceled before a work item can be dequeued.

Enqueue(T)

Adds an element to the tail of the queue.

public void Enqueue(T value)

Parameters

value T

The value to add.

Exceptions

InvalidOperationException

Thrown if Complete() has already been called. Use TryEnqueue(T) to avoid an exception in this case.

OnCompleted()

Invoked when the queue is completed.

protected virtual void OnCompleted()

OnDequeued(T)

Invoked when a value is dequeued.

protected virtual void OnDequeued(T value)

Parameters

value T

The dequeued value.

OnEnqueued(T, bool)

Invoked when a value is enqueued.

protected virtual void OnEnqueued(T value, bool alreadyDispatched)

Parameters

value T

The enqueued value.

alreadyDispatched bool

true if the item will skip the queue because a dequeuer was already waiting for an item; false if the item was actually added to the queue.

Peek()

Gets the value at the head of the queue without removing it from the queue.

public T Peek()

Returns

T

Exceptions

InvalidOperationException

Thrown if the queue is empty.

ToArray()

Returns a copy of this queue as an array.

public T[] ToArray()

Returns

T[]

TryDequeue(Predicate<T>, out T)

Immediately dequeues the element from the head of the queue if one is available that satisfies the specified check; otherwise returns without an element.

protected bool TryDequeue(Predicate<T> valueCheck, out T value)

Parameters

valueCheck Predicate<T>

The test on the head element that must succeed to dequeue.

value T

Receives the element from the head of the queue; or default(T) if the queue is empty.

Returns

bool

true if an element was dequeued; false if the queue was empty.

TryDequeue(out T)

Immediately dequeues the element from the head of the queue if one is available, otherwise returns without an element.

public bool TryDequeue(out T value)

Parameters

value T

Receives the element from the head of the queue; or default(T) if the queue is empty.

Returns

bool

true if an element was dequeued; false if the queue was empty.

TryEnqueue(T)

Adds an element to the tail of the queue if it has not yet completed.

public bool TryEnqueue(T value)

Parameters

value T

The value to add.

Returns

bool

true if the value was added to the queue; false if the queue is already completed.

TryPeek(out T)

Gets the value at the head of the queue without removing it from the queue, if it is non-empty.

public bool TryPeek(out T value)

Parameters

value T

Receives the value at the head of the queue; or the default value for the element type if the queue is empty.

Returns

bool

true if the queue was non-empty; false otherwise.