Class AsyncExclusiveLock

Represents asynchronous mutually exclusive lock.

Inheritance

object

Disposable

QueuedSynchronizer

AsyncExclusiveLock

Implements

IDisposable

IAsyncDisposable

Inherited Members

QueuedSynchronizer.CancelSuspendedCallers(CancellationToken)

QueuedSynchronizer.Dispose(bool)

QueuedSynchronizer.Dispose(Exception)

QueuedSynchronizer.DisposeAsyncCore()

QueuedSynchronizer.DisposeAsync()

QueuedSynchronizer.TrackSuspendedCallers(Func<object>)

QueuedSynchronizer.SetCallerInformation(object)

QueuedSynchronizer.GetSuspendedCallers()

QueuedSynchronizer.ConcurrencyLevel

QueuedSynchronizer.HasConcurrencyLimit

QueuedSynchronizer.MeasurementTags

Disposable.CreateException()

Disposable.GetDisposedTask<T>()

Disposable.TrySetDisposedException<T>(TaskCompletionSource<T>)

Disposable.TrySetDisposedException(TaskCompletionSource)

Disposable.TryBeginDispose()

Disposable.Dispose()

Disposable.Dispose(IEnumerable<IDisposable>)

Disposable.DisposeAsync(params IEnumerable<IAsyncDisposable>)

Disposable.Dispose<TDisposable>(params ReadOnlySpan<TDisposable>)

Disposable.IsDisposed

Disposable.IsDisposing

Disposable.IsDisposingOrDisposed

Disposable.DisposedTask

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Namespace: DotNext.Threading

Assembly: DotNext.Threading.dll

Syntax

public class AsyncExclusiveLock : QueuedSynchronizer, IDisposable, IAsyncDisposable

Constructors

AsyncExclusiveLock()

Initializes a new asynchronous exclusive lock.

Declaration

public AsyncExclusiveLock()

Properties

IsLockHeld

Indicates that exclusive lock taken.

Declaration

public bool IsLockHeld { get; }

Property Value

Type	Description
bool

Methods

AcquireAsync(CancellationToken)

Enters the lock in exclusive mode asynchronously.

Declaration

public ValueTask AcquireAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to abort lock acquisition.

Returns

Type	Description
ValueTask	The task representing lock acquisition operation.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Time-out value is negative.
ObjectDisposedException	This object has been disposed.
OperationCanceledException	The operation has been canceled.
PendingTaskInterruptedException	The operation has been interrupted manually.

AcquireAsync(TimeSpan, CancellationToken)

Enters the lock in exclusive mode asynchronously.

Declaration

public ValueTask AcquireAsync(TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
TimeSpan	timeout	The interval to wait for the lock.
CancellationToken	token	The token that can be used to abort lock acquisition.

Returns

Type	Description
ValueTask	The task representing lock acquisition operation.

Exceptions

Type	Condition
ArgumentOutOfRangeException	timeout is negative.
ObjectDisposedException	This object has been disposed.
TimeoutException	The lock cannot be acquired during the specified amount of time.
OperationCanceledException	The operation has been canceled.
PendingTaskInterruptedException	The operation has been interrupted manually.

Release()

Releases previously acquired exclusive lock.

Declaration

public void Release()

Exceptions

Type	Condition
SynchronizationLockException	The caller has not entered the lock.
ObjectDisposedException	This object has been disposed.

StealAsync(object?, CancellationToken)

Interrupts all pending callers in the queue and acquires the lock.

Declaration

public ValueTask StealAsync(object? reason = null, CancellationToken token = default)

Parameters

Type	Name	Description
object	reason	The reason for lock steal.
CancellationToken	token	The token that can be used to abort lock acquisition.

Returns

Type	Description
ValueTask	The task representing lock acquisition operation.

Remarks

PendingTaskInterruptedException will be thrown for each suspended caller in the queue. The method cannot interrupt the caller that has already acquired the lock. If there is no suspended callers in the queue, this method is equivalent to TryAcquireAsync(TimeSpan, CancellationToken).

Exceptions

Type	Condition
ArgumentOutOfRangeException	Time-out value is negative.
ObjectDisposedException	This object has been disposed.
OperationCanceledException	The operation has been canceled.

See Also

PendingTaskInterruptedException

StealAsync(object?, TimeSpan, CancellationToken)

Interrupts all pending callers in the queue and acquires the lock.

Declaration

public ValueTask StealAsync(object? reason, TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
object	reason	The reason for lock steal.
TimeSpan	timeout	The interval to wait for the lock.
CancellationToken	token	The token that can be used to abort lock acquisition.

Returns

Type	Description
ValueTask	The task representing lock acquisition operation.

Remarks

PendingTaskInterruptedException will be thrown for each suspended caller in the queue. The method cannot interrupt the caller that has already acquired the lock. If there is no suspended callers in the queue, this method is equivalent to TryAcquireAsync(TimeSpan, CancellationToken).

Exceptions

Type	Condition
ArgumentOutOfRangeException	Time-out value is negative.
ObjectDisposedException	This object has been disposed.
TimeoutException	The lock cannot be acquired during the specified amount of time.
OperationCanceledException	The operation has been canceled.

See Also

PendingTaskInterruptedException

TryAcquire()

Attempts to obtain exclusive lock synchronously without blocking caller thread.

Declaration

public bool TryAcquire()

Returns

Type	Description
bool	true if lock is taken successfully; otherwise, false.

Remarks

This method doesn't set thread ownership for this lock. Use TryAcquire(TimeSpan, CancellationToken) with Zero argument instead.

Exceptions

Type	Condition
ObjectDisposedException	This object has been disposed.

TryAcquire(TimeSpan, CancellationToken)

Tries to acquire the lock synchronously.

Declaration

public bool TryAcquire(TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
TimeSpan	timeout	The interval to wait for the lock.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
bool	true if the lock is acquired in timely manner; false if canceled or timed out.

Remarks

Do not release the lock acquired by this method in another thread.

Exceptions

Type	Condition
ArgumentOutOfRangeException	timeout is negative.
ObjectDisposedException	This object has been disposed.
LockRecursionException	The lock is already acquired by the current thread.

TryAcquireAsync(TimeSpan, CancellationToken)

Tries to enter the lock in exclusive mode asynchronously, with an optional time-out.

Declaration

public ValueTask<bool> TryAcquireAsync(TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
TimeSpan	timeout	The interval to wait for the lock.
CancellationToken	token	The token that can be used to abort lock acquisition.

Returns

Type	Description
ValueTask<bool>	true if the caller entered exclusive mode; otherwise, false.

Exceptions

Type	Condition
ArgumentOutOfRangeException	timeout is negative.
ObjectDisposedException	This object has been disposed.
OperationCanceledException	The operation has been canceled.
PendingTaskInterruptedException	The operation has been interrupted manually.

TryStealAsync(object?, TimeSpan, CancellationToken)

Interrupts all pending callers in the queue and acquires the lock.

Declaration

public ValueTask<bool> TryStealAsync(object? reason, TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
object	reason	The reason for lock steal.
TimeSpan	timeout	The interval to wait for the lock.
CancellationToken	token	The token that can be used to abort lock acquisition.

Returns

Type	Description
ValueTask<bool>	true if the caller entered exclusive mode; otherwise, false.

Remarks

PendingTaskInterruptedException will be thrown for each suspended caller in the queue. The method cannot interrupt the caller that has already acquired the lock. If there is no suspended callers in the queue, this method is equivalent to TryAcquireAsync(TimeSpan, CancellationToken).

Exceptions

Type	Condition
ArgumentOutOfRangeException	Time-out value is negative.
ObjectDisposedException	This object has been disposed.
OperationCanceledException	The operation has been canceled.

See Also

PendingTaskInterruptedException

YieldAsync(CancellationToken)

Temporarily releases the lock to let the suspended callers in, and then reacquires it.

Declaration

public ValueTask YieldAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to abort lock reacquisition.

Returns

Type	Description
ValueTask	The task representing lock reacquisition.

Remarks

If there are no suspended callers, the method completes synchronously and the lock remains held by the caller. Otherwise, the lock is passed to the first suspended caller, and the current caller is placed at the head of the wait queue. Thus, it reacquires the lock ahead of the callers suspended by AcquireAsync(CancellationToken) and similar methods. Callers that keep yielding to each other in a loop can starve the callers suspended by regular acquisition methods.
The caller must restore the invariants of the protected state before calling this method, because other callers can observe and modify that state while the lock is yielded.
If reacquisition is canceled or interrupted, the method throws an exception, and the lock is no longer held by the caller. In this case, the caller must not call Release(): the lock might be already acquired by another caller. Track the lock state explicitly to release the lock correctly:

var lockTaken = false;
await exclusiveLock.AcquireAsync(token);
lockTaken = true;
try
{
    // ...
    lockTaken = false;
    await exclusiveLock.YieldAsync(token);
    lockTaken = true;
    // ...
}
finally
{
    if (lockTaken)
        exclusiveLock.Release();
}

Exceptions

Type	Condition
SynchronizationLockException	The caller has not entered the lock.
InvalidOperationException	The lock is acquired synchronously by TryAcquire(TimeSpan, CancellationToken). In this case, the lock remains held by the caller.
ObjectDisposedException	This object has been disposed. If the object is being disposed gracefully with DisposeAsync(), the lock is released and not held by the caller.
OperationCanceledException	The operation has been canceled. The lock is not held by the caller.
PendingTaskInterruptedException	The operation has been interrupted manually. The lock is not held by the caller.

Implements

IDisposable

IAsyncDisposable

Extension Methods

BasicExtensions.As<T>(T)

BasicExtensions.IsBetween<T, TLowerBound, TUpperBound>(T, TLowerBound, TUpperBound)

BasicExtensions.IsOneOf<T>(T, params ReadOnlySpan<T>)