AsyncCountdownEvent Class

Definition

Namespace

Bodu.Threading

Assembly

Bodu.Core.dll

Package

Bodu.Core 1.0.1

Source

AsyncCountdownEvent.cs

Provides an asynchronous countdown synchronization primitive that becomes signaled once its count reaches zero, releasing all waiters.

public sealed class AsyncCountdownEvent

Inheritance

object

AsyncCountdownEvent

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

// Wait for a fixed number of parallel jobs to finish (fan-in).
var remaining = new AsyncCountdownEvent(initialCount: 3);

foreach (var job in jobs)
    _ = Task.Run(async () =>
    {
        await job.RunAsync();
        remaining.Signal(); // last Signal drives the count to zero
    });

await remaining.WaitAsync(); // completes once all three have signaled

Remarks

AsyncCountdownEvent is the asynchronous analogue of CountdownEvent. It starts with a positive count; each Signal() decrements the count, and when the count reaches zero every caller awaiting WaitAsync() is released. The count may be raised again with AddCount() while it is still above zero.

The releasing gate is an inner AsyncManualResetEvent, so continuations never run inline on the thread that drives the count to zero. The type owns no operating-system handle and does not implement IDisposable.

Unlike CountdownEvent, this type is not resettable: once the count reaches zero the event stays signaled and the count cannot be raised again. Create a new instance to count down a second time.

Constructors

AsyncCountdownEvent(int)

Initializes a new instance of the AsyncCountdownEvent class with the specified initial count.

public AsyncCountdownEvent(int initialCount)

Parameters

initialCount int

The number of signals required to set the event. A value of zero creates an already-signaled event.

Exceptions

ArgumentOutOfRangeException

initialCount is negative.

Properties

CurrentCount

Gets the number of remaining signals required to set the event.

public int CurrentCount { get; }

Property Value

int

The current count.

IsSet

Gets a value indicating whether the event is signaled (its count has reached zero).

public bool IsSet { get; }

Property Value

bool

true if the count is zero; otherwise, false.

Methods

AddCount()

Increments the count by one.

public void AddCount()

Exceptions

InvalidOperationException

The event is already signaled (its count is zero).

AddCount(int)

Increments the count by the specified amount.

public void AddCount(int count)

Parameters

count int

The amount by which to increase the count.

Exceptions

ArgumentOutOfRangeException

count is less than one.

InvalidOperationException

The event is already signaled (its count is zero), or increasing the count by count would overflow MaxValue.

Signal()

Registers a single signal, decrementing the count.

public bool Signal()

Returns

bool

true if the signal caused the count to reach zero; otherwise, false.

Exceptions

InvalidOperationException

The event is already signaled (its count is zero).

Signal(int)

Registers the specified number of signals, decrementing the count.

public bool Signal(int signalCount)

Parameters

signalCount int

The number of signals to register.

Returns

bool

true if the signals caused the count to reach zero; otherwise, false.

Exceptions

ArgumentOutOfRangeException

signalCount is less than one.

InvalidOperationException

signalCount is greater than the remaining count.

TryAddCount()

Attempts to increment the count by one.

public bool TryAddCount()

Returns

bool

true if the count was incremented; false if the event is already signaled.

TryAddCount(int)

Attempts to increment the count by the specified amount.

public bool TryAddCount(int count)

Parameters

count int

The amount by which to increase the count.

Returns

bool

true if the count was incremented; false if the event is already signaled.

Exceptions

ArgumentOutOfRangeException

count is less than one.

InvalidOperationException

Increasing the count by count would overflow MaxValue.

WaitAsync()

Asynchronously waits until the count reaches zero.

public ValueTask WaitAsync()

Returns

ValueTask

A ValueTask that completes when the event is signaled.

WaitAsync(CancellationToken)

Asynchronously waits until the count reaches zero, observing a cancellation request while waiting.

public ValueTask WaitAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A token used to cancel the wait.

Returns

ValueTask

A ValueTask that completes when the event is signaled.

Exceptions

OperationCanceledException

cancellationToken was canceled before the event was signaled.

Applies to

Product	Versions
.NET	8, 10