Shared delegates

Author: soenneker

src/Abstract/BackgroundQueueDelegates.cs

@@ -0,0 +1,27 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Soenneker.Utils.BackgroundQueue.Abstract;
+
+/// <summary>
+/// Represents an asynchronous work item that operates on a provided state and supports cancellation.
+/// </summary>
+/// <remarks>Use this delegate to define asynchronous operations that require state and support
+/// cancellation. The operation should observe the provided cancellation token and complete the returned ValueTask
+/// when finished or canceled.</remarks>
+/// <typeparam name="TState">The type of the state object to be passed to the work item.</typeparam>
+/// <param name="state">The state object to be used by the work item. The type and meaning of this value are determined by the caller.</param>
+/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
+/// <returns>A ValueTask that represents the asynchronous operation of the work item.</returns>
+public delegate ValueTask ValueTaskWorkItem<in TState>(TState state, CancellationToken cancellationToken);
+
+/// <summary>
+/// Represents an asynchronous work item that executes with a specified state and supports cancellation.
+/// </summary>
+/// <remarks>The delegate should honor the cancellation request by observing the provided cancellation
+/// token and responding appropriately if cancellation is requested.</remarks>
+/// <typeparam name="TState">The type of the state object to be passed to the work item.</typeparam>
+/// <param name="state">The state object to be used by the work item during execution.</param>
+/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
+/// <returns>A task that represents the asynchronous operation.</returns>
+public delegate Task TaskWorkItem<in TState>(TState state, CancellationToken cancellationToken);

src/Abstract/IBackgroundQueue.cs

@@ -13,6 +13,30 @@ namespace Soenneker.Utils.BackgroundQueue.Abstract;
 /// </remarks>
 public interface IBackgroundQueue
 {
+    /// <summary>
+    /// Queues a work item represented by a ValueTask for execution, passing the specified state to the work item
+    /// delegate.
+    /// </summary>
+    /// <typeparam name="TState">The type of the state object to pass to the work item.</typeparam>
+    /// <param name="state">The state object to pass to the work item delegate when it is executed.</param>
+    /// <param name="workItem">A delegate that represents the work to execute. The delegate receives the provided state object.</param>
+    /// <param name="cancellationToken">A cancellation token that can be used to cancel the queued work item before it starts executing. The default
+    /// value is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A ValueTask that represents the queued work item. The task completes when the work item has finished executing.</returns>
+    ValueTask QueueValueTask<TState>(TState state, ValueTaskWorkItem<TState> workItem, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Queues a work item for execution, passing the specified state to the provided delegate.
+    /// </summary>
+    /// <typeparam name="TState">The type of the state object to pass to the work item.</typeparam>
+    /// <param name="state">The state object to pass to the work item when it is executed.</param>
+    /// <param name="workItem">A delegate that represents the work item to execute. The delegate receives the specified state object.</param>
+    /// <param name="cancellationToken">A cancellation token that can be used to cancel the queued work item before it starts executing. The default
+    /// value is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ValueTask"/> that represents the queued work item. The task completes when the work item has been
+    /// executed or canceled.</returns>
+    ValueTask QueueTask<TState>(TState state, TaskWorkItem<TState> workItem, CancellationToken cancellationToken = default);
+
     /// <summary>
     /// Queues a <see cref="ValueTask"/> to be executed by the background service.
     /// </summary>

src/BackgroundQueue.cs

@@ -17,10 +17,6 @@ namespace Soenneker.Utils.BackgroundQueue;
 /// <inheritdoc cref="IBackgroundQueue"/>
 public sealed class BackgroundQueue : IBackgroundQueue
 {
-    public delegate ValueTask ValueTaskWorkItem<in TState>(TState state, CancellationToken ct);
-
-    public delegate Task TaskWorkItem<in TState>(TState state, CancellationToken ct);
-
     private readonly Channel<ValueTaskEnvelope> _valueTaskChannel;
     private readonly Channel<TaskEnvelope> _taskChannel;