Struct AsyncReaderWriterLock.Releaser
- Namespace
- CryptoHives.Foundation.Threading.Async.Pooled
- Assembly
- CryptoHives.Foundation.Threading.dll
A small value type returned by awaiting a lock acquisition. Disposing the releaser releases the lock.
public readonly struct AsyncReaderWriterLock.Releaser : IDisposable, IAsyncDisposable, IEquatable<AsyncReaderWriterLock.Releaser>- Implements
- Inherited Members
Remarks
Due to the different usage options for this releaser with the method to upgrade an upgradeable reader, it had been preferred to have a dedicated struct instead of using a common struct with flags to reduce the risk of incorrect usage. However multiple releaser struct types had resulted in seperate ObjectPools for each struct type which had reduced the overall pool efficiency and increased the memory usage, so a single struct with an enum to distinguish the different usage scenarios had been chosen as a good balance between usability and performance. Since any releaser can call the UpgradeToWriterLockAsync(CancellationToken) method, an InvalidOperationException is thrown if the method is called on a releaser that is not for the upgradeable reader state.
Methods
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()DisposeAsync()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.
public ValueTask DisposeAsync()Returns
Equals(Releaser)
Indicates whether the current object is equal to another object of the same type.
public bool Equals(AsyncReaderWriterLock.Releaser other)Parameters
otherAsyncReaderWriterLock.ReleaserAn object to compare with this object.
Returns
- bool
true if the current object is equal to the
otherparameter; otherwise, false.
Equals(object?)
Indicates whether this instance and a specified object are equal.
public override bool Equals(object? obj)Parameters
objobjectThe object to compare with the current instance.
Returns
- bool
true if
objand this instance are the same type and represent the same value; otherwise, false.
GetHashCode()
Returns the hash code for this instance.
public override int GetHashCode()Returns
- int
A 32-bit signed integer that is the hash code for this instance.
TryUpgradeToWriterLock(out Releaser)
Attempts to upgrade an upgradeable reader to a writer lock without waiting.
public bool TryUpgradeToWriterLock(out AsyncReaderWriterLock.Releaser releaser)Parameters
releaserAsyncReaderWriterLock.ReleaserThe releaser for the upgraded writer lock, if this method returns true. Dispose it to demote back to the upgradeable reader lock. Undefined if this method returns false.
Returns
Remarks
Synchronous and non-throwing for contention by design: unlike UpgradeToWriterLockAsync(TimeSpan, CancellationToken) with a zero timeout, a failed attempt here never allocates an exception or a faulted ValueTask<TResult> - it simply returns false while any other reader still holds the lock. Calling it on a releaser that is not in the upgradeable reader state is a programming error and still throws.
On success the current releaser stays valid: dispose the returned upgraded-writer releaser to drop back to the upgradeable reader lock, then dispose this one to release it entirely - exactly as with UpgradeToWriterLockAsync(CancellationToken).
Exceptions
- InvalidOperationException
Thrown if the current instance is not in the upgradeable reader state.
UpgradeToWriterLockAsync(CancellationToken)
Upgrades an upgradable reader to a writer lock.
public ValueTask<AsyncReaderWriterLock.Releaser> UpgradeToWriterLockAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationTokenA cancellation token that can be used to cancel the attempt to upgrade to the write lock.
Returns
Remarks
This method must only be called when the Releaser instance is in the upgradeable reader state. Failing to release the write lock by disposing the returned releaser may result in deadlocks.
Exceptions
- InvalidOperationException
Thrown if the current instance is not in the upgradeable reader state.
UpgradeToWriterLockAsync(TimeSpan, CancellationToken)
Upgrades an upgradable reader to a writer lock.
public ValueTask<AsyncReaderWriterLock.Releaser> UpgradeToWriterLockAsync(TimeSpan timeout, CancellationToken cancellationToken = default)Parameters
timeoutTimeSpanThe maximum time to wait. Use InfiniteTimeSpan to wait indefinitely.
cancellationTokenCancellationTokenA cancellation token that can be used to cancel the attempt to upgrade to the write lock.
Returns
Remarks
This method must only be called when the Releaser instance is in the upgradeable reader state. Failing to release the write lock by disposing the returned releaser may result in deadlocks.
Exceptions
- InvalidOperationException
Thrown if the current instance is not in the upgradeable reader state.
- TimeoutException
Thrown when the timeout elapses before the lock can be upgraded.
- OperationCanceledException
Thrown when
cancellationTokenis cancelled before the lock can be upgraded.
Operators
operator ==(Releaser, Releaser)
Determines whether two Releaser instances are equal.
public static bool operator ==(AsyncReaderWriterLock.Releaser left, AsyncReaderWriterLock.Releaser right)Parameters
Returns
operator !=(Releaser, Releaser)
Determines whether two Releaser instances are not equal.
public static bool operator !=(AsyncReaderWriterLock.Releaser left, AsyncReaderWriterLock.Releaser right)