Class AsyncRunOptions

Namespace

Cuemon.Threading

Assembly

Cuemon.Kernel.dll

Provides options that are related to asynchronous run operations.

public class AsyncRunOptions : AsyncOptions, IAsyncOptions, IValidatableParameterObject, IParameterObject

Inheritance

object

AsyncOptions

AsyncRunOptions

Implements

IAsyncOptions

IValidatableParameterObject

IParameterObject

Inherited Members

AsyncOptions.CancellationToken

AsyncOptions.CancellationTokenProvider

Examples

The following example demonstrates how to use to configure timeout, retry delay, maximum attempts, and inherited cancellation for an asynchronous operation.

using System;
using System.Threading;
using Cuemon.Threading;

namespace MyApp.Examples;

public class AsyncRunOptionsExample
{
    public void Demonstrate()
    {
        var options = new AsyncRunOptions
        {
            Timeout = TimeSpan.FromSeconds(30),
            Delay = TimeSpan.FromMilliseconds(500),
            MaximumAttempts = 3
        };
        Console.WriteLine(options.Timeout); // 00:00:30
        Console.WriteLine(options.Delay);   // 00:00:00.5000000
        Console.WriteLine(options.MaximumAttempts); // 3

        // Use with cancellation support
        var withCancellation = new AsyncRunOptions
        {
            Timeout = TimeSpan.FromSeconds(10),
            CancellationToken = new CancellationTokenSource(5000).Token
        };

        // Zero-delay retries require an explicit attempt limit
        var zeroDelay = new AsyncRunOptions
        {
            Timeout = TimeSpan.FromSeconds(1),
            Delay = TimeSpan.Zero,
            MaximumAttempts = 3
        };
        Console.WriteLine(zeroDelay.MaximumAttempts); // 3

        // Defaults: timeout 5s, delay 100ms
        var defaults = new AsyncRunOptions();
        Console.WriteLine(defaults.Timeout); // 00:00:05
        Console.WriteLine(defaults.Delay);   // 00:00:00.1000000
        Console.WriteLine(defaults.MaximumAttempts); // 0
        Console.WriteLine(withCancellation.CancellationToken.CanBeCanceled); // True
    }
}

Constructors

AsyncRunOptions()

Initializes a new instance of the AsyncRunOptions class.

public AsyncRunOptions()

Remarks

The following table shows the initial property values for an instance of AsyncRunOptions.

Property	Initial Value
Timeout	00:00:05 (5 seconds)
Delay	00:00:00.1000000 (100 milliseconds)
MaximumAttempts	0 (no explicit attempt limit)

Properties

Delay

Gets or sets the configured delay between unsuccessful asynchronous operation attempts.

public TimeSpan Delay { get; set; }

Property Value

TimeSpan

The configured delay between unsuccessful asynchronous operation attempts. The default is 100 milliseconds.

Remarks

The effective delay is capped to the remaining Timeout window. Positive fractional-millisecond delays are rounded up to the next whole millisecond when the retry delay is scheduled. The value must not be negative.

MaximumAttempts

Gets or sets the maximum number of total invocations, including the initial invocation.

public int MaximumAttempts { get; set; }

Property Value

int

The maximum number of total invocations. The default is 0.

Remarks

When this property is 0, retries continue until the operation succeeds, the Timeout window closes, or cancellation is requested. When Delay is Zero, this property must be configured with a positive value.

Timeout

Gets or sets the total retry window for the asynchronous operation.

public TimeSpan Timeout { get; set; }

Property Value

TimeSpan

The total retry window for the asynchronous operation. The default is 5 seconds.

Remarks

The retry window begins immediately before the initial invocation. A value of Zero still permits the initial invocation. The value must not be negative.

Methods

ValidateOptions()

Determines whether the public read-write properties of this instance are in a valid state.

public void ValidateOptions()

Remarks

This method is expected to throw exceptions when one or more conditions fails to be in a valid state.

Exceptions

InvalidOperationException

Timeout or Delay is negative. -or- MaximumAttempts is negative. -or- Delay is Zero and MaximumAttempts is not configured with a positive value.

See Also

AsyncOptions

IValidatableParameterObject