Class AsyncReaderWriterLock

Represents asynchronous version of ReaderWriterLockSlim.

Inheritance

object

Disposable

QueuedSynchronizer

AsyncReaderWriterLock

Implements

IDisposable

IAsyncDisposable

Inherited Members

QueuedSynchronizer.ConcurrencyLevel

QueuedSynchronizer.HasConcurrencyLimit

QueuedSynchronizer.CancelSuspendedCallers(CancellationToken)

QueuedSynchronizer.Dispose(Exception)

QueuedSynchronizer.DisposeAsyncCore()

QueuedSynchronizer.DisposeAsync()

QueuedSynchronizer.TrackSuspendedCallers(Func<object>)

QueuedSynchronizer.SetCallerInformation(object)

QueuedSynchronizer.GetSuspendedCallers()

QueuedSynchronizer.MeasurementTags

Disposable.IsDisposed

Disposable.IsDisposing

Disposable.IsDisposingOrDisposed

Disposable.CreateException()

Disposable.DisposedTask

Disposable.GetDisposedTask<T>()

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

Disposable.TrySetDisposedException(TaskCompletionSource)

Disposable.TryBeginDispose()

Disposable.Dispose()

Disposable.Dispose(IEnumerable<IDisposable>)

Disposable.DisposeAsync(IEnumerable<IAsyncDisposable>)

Disposable.Dispose<T>(ReadOnlySpan<T>)

Disposable.DisposeAsync(params IAsyncDisposable[])

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: DotNext.Threading

Assembly: DotNext.Threading.dll

Syntax

public class AsyncReaderWriterLock : QueuedSynchronizer, IDisposable, IAsyncDisposable

Remarks

This lock doesn't support recursion.

Constructors

AsyncReaderWriterLock()

Initializes a new reader/writer lock.

Declaration

public AsyncReaderWriterLock()

Properties

CurrentReadCount

Gets the total number of unique readers.

Declaration

public long CurrentReadCount { get; }

Property Value

Type	Description
long

IsReadLockHeld

Gets a value that indicates whether the read lock taken.

Declaration

public bool IsReadLockHeld { get; }

Property Value

Type	Description
bool

IsWriteLockHeld

Gets a value that indicates whether the write lock taken.

Declaration

public bool IsWriteLockHeld { get; }

Property Value

Type	Description
bool

Methods

Dispose(bool)

Releases all resources associated with this object.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	Indicates whether the Dispose(bool) has been called directly or from finalizer.

Overrides

QueuedSynchronizer.Dispose(bool)

Remarks

This method is not thread-safe and may not be used concurrently with other members of this instance.

DowngradeFromWriteLock()

Downgrades the write lock to the read lock.

Declaration

public void DowngradeFromWriteLock()

Remarks

Exiting from the lock is synchronous non-blocking operation. Lock acquisition is an asynchronous operation.

Exceptions

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

EnterReadLockAsync(CancellationToken)

Enters the lock in read mode asynchronously.

Declaration

public ValueTask EnterReadLockAsync(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 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.

EnterReadLockAsync(TimeSpan, CancellationToken)

Enters the lock in read mode asynchronously.

Declaration

public ValueTask EnterReadLockAsync(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 asynchronous result.

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.
PendingTaskInterruptedException	The operation has been interrupted manually.

EnterWriteLockAsync(CancellationToken)

Enters the lock in write mode asynchronously.

Declaration

public ValueTask EnterWriteLockAsync(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.

EnterWriteLockAsync(TimeSpan, CancellationToken)

Enters the lock in write mode asynchronously.

Declaration

public ValueTask EnterWriteLockAsync(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	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.
PendingTaskInterruptedException	The operation has been interrupted manually.

Release()

Exits previously acquired mode.

Declaration

public void Release()

Remarks

Exiting from the lock is synchronous non-blocking operation. Lock acquisition is an asynchronous operation.

Exceptions

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

StealWriteLockAsync(object?, CancellationToken)

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

Declaration

public ValueTask StealWriteLockAsync(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.

Exceptions

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

See Also

PendingTaskInterruptedException

StealWriteLockAsync(object?, TimeSpan, CancellationToken)

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

Declaration

public ValueTask StealWriteLockAsync(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.

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

TryEnterReadLock()

Tries to obtain reader lock synchronously without blocking caller thread.

Declaration

public bool TryEnterReadLock()

Returns

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

Exceptions

Type	Condition
ObjectDisposedException	This object has been disposed.

TryEnterReadLock(TimeSpan, CancellationToken)

Tries to obtain reader lock synchronously.

Declaration

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

Parameters

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

Returns

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

Exceptions

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

TryEnterReadLockAsync(TimeSpan, CancellationToken)

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

Declaration

public ValueTask<bool> TryEnterReadLockAsync(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 read mode; otherwise, false.

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.

TryEnterWriteLock()

Attempts to obtain writer lock synchronously without blocking caller thread.

Declaration

public bool TryEnterWriteLock()

Returns

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

Exceptions

Type	Condition
ObjectDisposedException	This object has been disposed.

TryEnterWriteLock(in LockStamp)

Attempts to acquire write lock without blocking.

Declaration

public bool TryEnterWriteLock(in AsyncReaderWriterLock.LockStamp stamp)

Parameters

Type	Name	Description
AsyncReaderWriterLock.LockStamp	stamp	The stamp of the read lock.

Returns

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

Exceptions

Type	Condition
ObjectDisposedException	This object has been disposed.

TryEnterWriteLock(TimeSpan, CancellationToken)

Tries to obtain writer lock synchronously.

Declaration

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

Parameters

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

Returns

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

Exceptions

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

TryEnterWriteLockAsync(TimeSpan, CancellationToken)

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

Declaration

public ValueTask<bool> TryEnterWriteLockAsync(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 write mode; otherwise, false.

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.

TryOptimisticRead()

Returns a stamp that can be validated later.

Declaration

public AsyncReaderWriterLock.LockStamp TryOptimisticRead()

Returns

Type	Description
AsyncReaderWriterLock.LockStamp	Optimistic read stamp. May be invalid.

Exceptions

Type	Condition
ObjectDisposedException	This object has been disposed.

TryStealWriteLockAsync(object?, TimeSpan, CancellationToken)

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

Declaration

public ValueTask<bool> TryStealWriteLockAsync(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 write mode; otherwise, false.

Exceptions

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

See Also

PendingTaskInterruptedException

TryUpgradeToWriteLock()

Tries to upgrade the read lock to the write lock synchronously without blocking of the caller.

Declaration

public bool TryUpgradeToWriteLock()

Returns

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

Remarks

When this method is called, the reader lock is released, and the caller goes to the end of the queue for the writer lock. Thus, other callers might write to the resource before the caller that requested the upgrade is granted the writer lock. If this method returns false, it doesn't reacquire the reader lock.

Examples

See example for UpgradeToWriteLockAsync(CancellationToken)

Exceptions

Type	Condition
ObjectDisposedException	This object has been disposed.
SynchronizationLockException	The caller wasn't acquire the reader lock.

TryUpgradeToWriteLockAsync(TimeSpan, CancellationToken)

Tries to upgrade the read lock to the write lock asynchronously.

Declaration

public ValueTask<bool> TryUpgradeToWriteLockAsync(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 upgradeable mode; otherwise, false.

Remarks

When this method is called, the reader lock is released, and the caller goes to the end of the queue for the writer lock. Thus, other callers might write to the resource before the caller that requested the upgrade is granted the writer lock. If this method fails or returns false, it doesn't reacquire the reader lock.

Examples

See example for UpgradeToWriteLockAsync(CancellationToken)

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.
SynchronizationLockException	The caller wasn't acquire the reader lock.

UpgradeToWriteLockAsync(CancellationToken)

Upgrades the read lock to the write lock asynchronously.

Declaration

public ValueTask UpgradeToWriteLockAsync(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.

Remarks

When this method is called, the reader lock is released, and the caller goes to the end of the queue for the writer lock. Thus, other callers might write to the resource before the caller that requested the upgrade is granted the writer lock. If this method fails, it doesn't reacquire the reader lock.

Examples

The recommended pattern for upgrade is the following:

AsyncReaderWriterLock rwl;
var lockTaken = false;
await rwl.EnterReadLockAsync(token);
lockTaken = true;
try
{
  // do read-only stuff ...
  // now upgrade the lock
  lockTaken = false;
  await rwl.UpgradeToWriteLockAsync(token);
  lockTaken = true;
  try
  {
    // do write
  }
  finally
  {
    rwl.DowngradeFromWriteLock();
  }
}
finally
{
  if (lockTaken)
    rwl.Release();
}

lockTaken is needed here because UpgradeToWriteLockAsync(CancellationToken) could throw, but

it always releases the reader lock. In that case, finally block should not release the reader lock twice.

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.
SynchronizationLockException	The caller wasn't acquire the reader lock.

UpgradeToWriteLockAsync(TimeSpan, CancellationToken)

Upgrades the read lock to the write lock asynchronously.

Declaration

public ValueTask UpgradeToWriteLockAsync(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.

Remarks

When this method is called, the reader lock is released, and the caller goes to the end of the queue for the writer lock. Thus, other callers might write to the resource before the caller that requested the upgrade is granted the writer lock. If this method fails, it doesn't reacquire the reader lock.

Examples

See example for UpgradeToWriteLockAsync(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.
PendingTaskInterruptedException	The operation has been interrupted manually.
SynchronizationLockException	The caller wasn't acquire the reader lock.

Validate(in LockStamp)

Returns true if the lock has not been exclusively acquired since issuance of the given stamp.

Declaration

public bool Validate(in AsyncReaderWriterLock.LockStamp stamp)

Parameters

Type	Name	Description
AsyncReaderWriterLock.LockStamp	stamp	A stamp to check.

Returns

Type	Description
bool	true if the lock has not been exclusively acquired since issuance of the given stamp; else false.

Implements

IDisposable

IAsyncDisposable

Extension Methods

BasicExtensions.As<T>(T)

BasicExtensions.GetUserData<T>(T)

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

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

ExpressionBuilder.Const<T>(T)