Class AsyncQueue<TItem>
Async queue that can be processed by an implementation of AsyncQueueProcessor<TItem>
Inherited Members
Namespace: SuperOffice.Threading
Assembly: SoCore.dll
Syntax
public class AsyncQueue<TItem> : AsyncQueueBase<TItem>, IAsyncQueueInstance, IAsyncQueue<TItem>, IAsyncQueueBase<TItem>Type Parameters
| Name | Description |
|---|---|
| TItem | Item to add and process in the queue |
Remarks
Get instance of the queue using ClassFactory or DI. ClassFactory.CreateRequired<IAsyncQueue<TItem>>()
This class contains both a queue and a mechanism to process items in the queue. Processing
is done by calling the ProcessNextItemAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method,
for instance from a BackgroundService that uses AsyncQueueProcessor<TQueue, TItem> as its base class.
Our own AsyncQueueBase<TItem> class contains the ProcessItemsAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method (note plural form of Items in its name!). This is the
method that contains the loop, which repeatedly calls our ProcessNextItemAsync method. This loop should only terminate
throught the CancellationToken it was set up with.
Constructors
AsyncQueue(INSPrincipalAccessor, ILogger<AsyncQueue<TItem>>, AsyncQueueTracker)
Async queue that can be processed by an implementation of AsyncQueueProcessor<TItem>
Declaration
public AsyncQueue(INSPrincipalAccessor principalAccessor, ILogger<AsyncQueue<TItem>> logger, AsyncQueueTracker tracker)Parameters
| Type | Name | Description |
|---|---|---|
| INSPrincipalAccessor | principalAccessor | |
| ILogger<AsyncQueue<TItem>> | logger | |
| AsyncQueueTracker | tracker |
Remarks
Get instance of the queue using ClassFactory or DI. ClassFactory.CreateRequired<IAsyncQueue<TItem>>()
This class contains both a queue and a mechanism to process items in the queue. Processing
is done by calling the ProcessNextItemAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method,
for instance from a BackgroundService that uses AsyncQueueProcessor<TQueue, TItem> as its base class.
Our own AsyncQueueBase<TItem> class contains the ProcessItemsAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method (note plural form of Items in its name!). This is the
method that contains the loop, which repeatedly calls our ProcessNextItemAsync method. This loop should only terminate
throught the CancellationToken it was set up with.
Properties
Count
Approximate count of items currently waiting in the queue (NOT including items currently being processed).
Declaration
public override int Count { get; }Property Value
| Type | Description |
|---|---|
| int |
Overrides
Remarks
Designed to be cheap (O(1) or O(segments)) so it is safe to call on hot paths
such as per-event diagnostic or auto-scaling decisions. Specifically does NOT
materialize a snapshot array — prefer this over ToArray(...).Length.
May read slightly stale values when other threads concurrently enqueue or
dequeue; acceptable for thresholding / metrics purposes.
HasItemsInTheQueue
True if there are items in the queue
Declaration
public override bool HasItemsInTheQueue { get; }Property Value
| Type | Description |
|---|---|
| bool |
Overrides
Remarks
Get instance of the queue using ClassFactory or DI. ClassFactory.CreateRequired<IAsyncQueue<TItem>>()
This class contains both a queue and a mechanism to process items in the queue. Processing
is done by calling the ProcessNextItemAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method,
for instance from a BackgroundService that uses AsyncQueueProcessor<TQueue, TItem> as its base class.
Our own AsyncQueueBase<TItem> class contains the ProcessItemsAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method (note plural form of Items in its name!). This is the
method that contains the loop, which repeatedly calls our ProcessNextItemAsync method. This loop should only terminate
throught the CancellationToken it was set up with.
Methods
DrainQueue()
Discard all items currently waiting in the queue without processing them. Each discarded item's completion task is transitioned to the Canceled state, so callers awaiting an individual item or WaitForItemsInQueueToBeProcessedAsync(CancellationToken) observe cancellation rather than hanging.
Declaration
public override int DrainQueue()Returns
| Type | Description |
|---|---|
| int | Number of items that were discarded. |
Overrides
Remarks
Items already in flight (handed to a worker via ProcessNextItemAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken)) are NOT canceled by this method — they finish naturally. Intended for shutdown and test-isolation scenarios where the caller has given up on waiting for the remaining backlog and wants to leave the queue in a clean state for subsequent work. Workers blocked on the inner signaling primitive may observe a small, bounded number of spurious wake-ups (one per drained item) and will exit those iterations immediately when they find the queue empty.
GetInnerQueueCompletionTasks()
Async queue that can be processed by an implementation of AsyncQueueProcessor<TItem>
Declaration
protected override IEnumerable<Task> GetInnerQueueCompletionTasks()Returns
| Type | Description |
|---|---|
| IEnumerable<Task> |
Overrides
Remarks
Get instance of the queue using ClassFactory or DI. ClassFactory.CreateRequired<IAsyncQueue<TItem>>()
This class contains both a queue and a mechanism to process items in the queue. Processing
is done by calling the ProcessNextItemAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method,
for instance from a BackgroundService that uses AsyncQueueProcessor<TQueue, TItem> as its base class.
Our own AsyncQueueBase<TItem> class contains the ProcessItemsAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method (note plural form of Items in its name!). This is the
method that contains the loop, which repeatedly calls our ProcessNextItemAsync method. This loop should only terminate
throught the CancellationToken it was set up with.
InnerEnqueue(AsyncQueueItem)
Async queue that can be processed by an implementation of AsyncQueueProcessor<TItem>
Declaration
protected override void InnerEnqueue(AsyncQueueBase<TItem>.AsyncQueueItem queItem)Parameters
| Type | Name | Description |
|---|---|---|
| AsyncQueueBase<TItem>.AsyncQueueItem | queItem |
Overrides
Remarks
Get instance of the queue using ClassFactory or DI. ClassFactory.CreateRequired<IAsyncQueue<TItem>>()
This class contains both a queue and a mechanism to process items in the queue. Processing
is done by calling the ProcessNextItemAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method,
for instance from a BackgroundService that uses AsyncQueueProcessor<TQueue, TItem> as its base class.
Our own AsyncQueueBase<TItem> class contains the ProcessItemsAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method (note plural form of Items in its name!). This is the
method that contains the loop, which repeatedly calls our ProcessNextItemAsync method. This loop should only terminate
throught the CancellationToken it was set up with.
ProcessNextItemAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken)
Block until an item can be picked off the queue, or the cancellation token is signaled.
Pick the top item off the queue and call the processor delegate.
Multiple calls (from separate Tasks) to this method are supported and will run in parallel
if there are multiple items in the queue.
Declaration
public override Task ProcessNextItemAsync(AsyncQueueProcessItemAsync<TItem> processor, CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| AsyncQueueProcessItemAsync<TItem> | processor | The concrete method to be called for an item, when an item becomes available |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Overrides
Remarks
This method contains the mechanisms needed to safely pick items off the queue, or block until an
item is available (in an async-friendly manner).
_itemsBeingProcessed contains the currently processing items. This is for information only.
ToArray(bool)
Get a snapshot of all the items in the queue
Declaration
public override TItem[] ToArray(bool includeItemsBeingProcessed)Parameters
| Type | Name | Description |
|---|---|---|
| bool | includeItemsBeingProcessed | Include items currently being processed in the snapshot |
Returns
| Type | Description |
|---|---|
| TItem[] |
Overrides
Remarks
Get instance of the queue using ClassFactory or DI. ClassFactory.CreateRequired<IAsyncQueue<TItem>>()
This class contains both a queue and a mechanism to process items in the queue. Processing
is done by calling the ProcessNextItemAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method,
for instance from a BackgroundService that uses AsyncQueueProcessor<TQueue, TItem> as its base class.
Our own AsyncQueueBase<TItem> class contains the ProcessItemsAsync(AsyncQueueProcessItemAsync<TItem>, CancellationToken) method (note plural form of Items in its name!). This is the
method that contains the loop, which repeatedly calls our ProcessNextItemAsync method. This loop should only terminate
throught the CancellationToken it was set up with.