Class AsyncBackgroundLoopController

Namespace

Acuit.Pinpoint.Common.Threading

Assembly

Acuit.Pinpoint.Common.dll

Provides control over the execution of an asynchronous background loop, where the loop will run until requested to stop via a cancellation token.

public sealed class AsyncBackgroundLoopController : IDisposable, IAsyncDisposable

Inheritance

object

AsyncBackgroundLoopController

Implements

IDisposable

IAsyncDisposable

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

AsyncBackgroundLoopController()

public AsyncBackgroundLoopController()

Properties

IsExecuting

Gets whether the background loop is currently executing.

public bool IsExecuting { get; }

Property Value

bool

LoopUnhandledExceptionHandler

Gets or sets an optional handler that will be invoked if the background loop completes due to an unhandled exception.

public Action<AggregateException>? LoopUnhandledExceptionHandler { get; set; }

Property Value

Action<AggregateException>

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Remarks

If the background loop is executing when this is called, this will signal a stop request via the cancellation token, but it will not wait for the background loop to finish executing.

If the background loop completes with a fault:

• If LoopUnhandledExceptionHandler has been set, it will be invoked.
• If LoopUnhandledExceptionHandler has not been set, it will result in an unobserved task exception when the task finalizer runs.

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

Remarks

If the background loop is executing when this is called, this will signal a stop request via the cancellation token, and then will wait for the background loop to finish executing.

If the background loop completes with a fault:

• If LoopUnhandledExceptionHandler has been set, it will be invoked.
• If LoopUnhandledExceptionHandler has not been set, the unhandled exception will be eaten.

Start(Func<CancellationToken, Task>)

Starts executing the asynchronous background loop.

public void Start(Func<CancellationToken, Task> loopTaskFunc)

Parameters

loopTaskFunc Func<CancellationToken, Task>

A function that starts executing the asynchronous background loop. It takes a CancellationToken parameter that will be signaled when the loop should stop, and returns a Task that represents the loop execution.

Remarks

loopTaskFunc will be invoked on the current thread; the caller is responsible for ensuring this executes asynchronously as appropriate (e.g., by using Run(Func<Task>) if necessary).

If loopTaskFunc throws an exception synchronously, it will be be propagated to the caller of Start(Func<CancellationToken, Task>).

If loopTaskFunc completes with a fault through the returned Task:

• If LoopUnhandledExceptionHandler has been set, it will be invoked.
• If LoopUnhandledExceptionHandler has not been set, the unhandled exception will be thrown when StopAsync(CancellationToken) or Stop(TimeSpan) is called.

Exceptions

ArgumentNullException

loopTaskFunc is null.

InvalidOperationException

The background loop is already running.

Exception

The loopTaskFunc function threw an exception synchronously.

Stop(TimeSpan)

Stops the background loop, if it is executing.

public bool Stop(TimeSpan timeout)

Parameters

timeout TimeSpan

How long to wait for the background loop to stop.

Returns

bool

true if the background loop stopped successfully (or wasn't executing to begin with), or false if the timeout expired before the background loop stopped.

Remarks

If the background loop completes with a fault:

• If LoopUnhandledExceptionHandler has been set, it will be invoked.
• If LoopUnhandledExceptionHandler has not been set, the exception will be propagated to the caller of this method.

If the background loop does not stop before timeout expires, any still-executing background loop will be abandoned, allowing a new background loop to be started. If the abandoned background loop eventually completes with a fault:

• If LoopUnhandledExceptionHandler has been set, it will be invoked.
• If LoopUnhandledExceptionHandler has not been set, it will result in an unobserved task exception when the task finalizer runs.

Exceptions

InvalidOperationException

Stopping the background loop is already in progress.

Exception

The background loop completed with a fault and LoopUnhandledExceptionHandler is not set.

StopAsync(CancellationToken)

Stops the background loop, if it is executing.

public Task StopAsync(CancellationToken cancellation = default)

Parameters

cancellation CancellationToken

A token that can request cancellation of waiting on the background loop to stop.

Returns

Task

The task object representing the asynchronous operation.

Remarks

If the background loop completes with a fault:

• If LoopUnhandledExceptionHandler has been set, it will be invoked.
• If LoopUnhandledExceptionHandler has not been set, the exception will be propagated to the caller of this method.

If waiting on the background loop to stop is canceled via cancellation, any still-executing background loop will be abandoned, allowing a new background loop to be started. If the abandoned background loop eventually completes with a fault:

• If LoopUnhandledExceptionHandler has been set, it will be invoked.
• If LoopUnhandledExceptionHandler has not been set, it will result in an unobserved task exception when the task finalizer runs.

Exceptions

InvalidOperationException

Stopping the background loop is already in progress.

Exception

The background loop completed with a fault and LoopUnhandledExceptionHandler is not set.