Class LeaseProvider<TMetadata>

Represents provider side of a lease in a distributed environment.

Inheritance

object

Disposable

LeaseProvider<TMetadata>

Implements

IDisposable

Inherited Members

Disposable.IsDisposed

Disposable.IsDisposing

Disposable.IsDisposingOrDisposed

Disposable.CreateException()

Disposable.DisposedTask

Disposable.GetDisposedTask<T>()

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

Disposable.TrySetDisposedException(TaskCompletionSource)

Disposable.DisposeAsyncCore()

Disposable.DisposeAsync()

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.Leases

Assembly: DotNext.Threading.dll

Syntax

public abstract class LeaseProvider<TMetadata> : Disposable, IDisposable

Type Parameters

Name	Description
TMetadata	The type of metadata associated with a lease.

Remarks

An instance of this type must support concurrent calls.

Constructors

LeaseProvider(TimeSpan, TimeProvider?)

Initializes a new instance of lease provider.

Declaration

protected LeaseProvider(TimeSpan ttl, TimeProvider? provider = null)

Parameters

Type	Name	Description
TimeSpan	ttl	The lease expiration timeout.
TimeProvider	provider	The time provider.

Exceptions

Type	Condition
ArgumentOutOfRangeException	ttl is not positive or greater than MaxTimeoutParameterTicks.

Properties

LifetimeToken

A token that represents state of this object.

Declaration

protected CancellationToken LifetimeToken { get; }

Property Value

Type	Description
CancellationToken

Remarks

A call to Dispose(bool) cancels the token.

TimeToLive

Gets a lease time-to-live.

Declaration

public TimeSpan TimeToLive { get; }

Property Value

Type	Description
TimeSpan

Methods

AcquireAsync(CancellationToken)

Acquires the lease.

Declaration

public ValueTask<LeaseProvider<TMetadata>.AcquisitionResult> AcquireAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseProvider<TMetadata>.AcquisitionResult>	The status of the operation.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.

AcquireAsync<TArg>(TArg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>, CancellationToken)

Acquires the lease.

Declaration

public ValueTask<LeaseProvider<TMetadata>.AcquisitionResult> AcquireAsync<TArg>(TArg arg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>> updater, CancellationToken token = default)

Parameters

Type	Name	Description
TArg	arg	The argument to be passed to the metadata updater.
Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>	updater	An idempotent operation to update the metadata on successful acquisition of the lease.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseProvider<TMetadata>.AcquisitionResult>	The status of the operation.

Type Parameters

Name	Description
TArg	The type of the argument to be passed to the metadata updater.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.
ArgumentNullException	updater is null.

Dispose(bool)

Releases managed and unmanaged resources associated with this object.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	true if called from Dispose(); false if called from finalizer ~Disposable().

Overrides

Disposable.Dispose(bool)

GetStateAsync(CancellationToken)

Loads the state of a lease from the underlying storage.

Declaration

protected abstract ValueTask<LeaseProvider<TMetadata>.State> GetStateAsync(CancellationToken token)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseProvider<TMetadata>.State>	The state restored from the underlying storage.

Remarks

The method can be called concurrently.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.

ReleaseAsync(LeaseIdentity, CancellationToken)

Releases the lease.

Declaration

public ValueTask<LeaseIdentity?> ReleaseAsync(LeaseIdentity identity, CancellationToken token = default)

Parameters

Type	Name	Description
LeaseIdentity	identity	The identity of the lease obtained from TryAcquireAsync(CancellationToken) or AcquireAsync(CancellationToken).
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseIdentity?>	Updated lease identity; or null if expired or taken by another process.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.

ReleaseAsync<TArg>(LeaseIdentity, TArg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>, CancellationToken)

Releases the lease.

Declaration

public ValueTask<LeaseIdentity?> ReleaseAsync<TArg>(LeaseIdentity identity, TArg arg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>> updater, CancellationToken token = default)

Parameters

Type	Name	Description
LeaseIdentity	identity	The identity of the lease obtained from TryAcquireAsync(CancellationToken) or AcquireAsync(CancellationToken).
TArg	arg	The argument to be passed to the metadata updater.
Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>	updater	An idempotent operation to update the metadata on successful acquisition of the lease.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseIdentity?>	Updated lease identity; or null if expired or taken by another process.

Type Parameters

Name	Description
TArg	The type of the argument to be passed to the metadata updater.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.
ArgumentNullException	updater is null.

TryAcquireAsync(CancellationToken)

Tries to acquire the lease.

Declaration

public ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?> TryAcquireAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?>	The acquisition result; or null if the lease is already taken.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.

TryAcquireAsync<TArg>(TArg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>, CancellationToken)

Tries to acquire the lease.

Declaration

public ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?> TryAcquireAsync<TArg>(TArg arg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>> updater, CancellationToken token = default)

Parameters

Type	Name	Description
TArg	arg	The argument to be passed to the metadata updater.
Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>	updater	An idempotent operation to update the metadata on successful acquisition of the lease.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?>	The acquisition result; or null if the lease is already taken.

Type Parameters

Name	Description
TArg	The type of the argument to be passed to the metadata updater.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.
ArgumentNullException	updater is null.

TryAcquireOrRenewAsync(LeaseIdentity, CancellationToken)

Tries to acquire or renew the lease.

Declaration

public ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?> TryAcquireOrRenewAsync(LeaseIdentity identity, CancellationToken token = default)

Parameters

Type	Name	Description
LeaseIdentity	identity	The identity of the lease obtained from TryAcquireAsync(CancellationToken) or AcquireAsync(CancellationToken).
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?>	The status of the operation; or null if the lease is taken by another process.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.

TryAcquireOrRenewAsync<TArg>(LeaseIdentity, TArg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>, CancellationToken)

Tries to acquire or renew the lease.

Declaration

public ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?> TryAcquireOrRenewAsync<TArg>(LeaseIdentity identity, TArg arg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>> updater, CancellationToken token = default)

Parameters

Type	Name	Description
LeaseIdentity	identity	The identity of the lease obtained from TryAcquireAsync(CancellationToken) or AcquireAsync(CancellationToken).
TArg	arg	The argument to be passed to the metadata updater.
Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>	updater	An idempotent operation to update the metadata on successful acquisition of the lease.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?>	The status of the operation; or null if the lease is taken by another process.

Type Parameters

Name	Description
TArg	The type of the argument to be passed to the metadata updater.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.

TryRenewAsync(LeaseIdentity, bool, CancellationToken)

Tries to renew the lease.

Declaration

public ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?> TryRenewAsync(LeaseIdentity identity, bool reacquire, CancellationToken token = default)

Parameters

Type	Name	Description
LeaseIdentity	identity	The identity of the lease obtained from TryAcquireAsync(CancellationToken) or AcquireAsync(CancellationToken).
bool	reacquire	true to acquire the lease on renewal if it is expired.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?>	The status of the operation; or null if the lease is taken by another process or expired.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.

TryRenewAsync<TArg>(LeaseIdentity, bool, TArg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>, CancellationToken)

Tries to renew the lease.

Declaration

public ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?> TryRenewAsync<TArg>(LeaseIdentity identity, bool reacquire, TArg arg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>> updater, CancellationToken token = default)

Parameters

Type	Name	Description
LeaseIdentity	identity	The identity of the lease obtained from TryAcquireAsync(CancellationToken) or AcquireAsync(CancellationToken).
bool	reacquire	true to acquire the lease on renewal if it is expired.
TArg	arg	The argument to be passed to the metadata updater.
Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>	updater	An idempotent operation to update the metadata on successful acquisition of the lease.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseProvider<TMetadata>.AcquisitionResult?>	The status of the operation; or null if the lease is taken by another process or expired.

Type Parameters

Name	Description
TArg	The type of the argument to be passed to the metadata updater.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.
ArgumentNullException	updater is null.

TryUpdateStateAsync(State, CancellationToken)

Attempts to update the state in the underlying storage using compare-and-set semantics.

Declaration

protected abstract ValueTask<bool> TryUpdateStateAsync(LeaseProvider<TMetadata>.State state, CancellationToken token)

Parameters

Type	Name	Description
LeaseProvider<TMetadata>.State	state	The state to be stored in the underlying storage.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<bool>	true if update is performed successfully; false is compare-and-set failed.

Remarks

The operation must use compare-and-set semantics in the following way: save state only if Version of the currently stored state is equal to the version of state - 1. Note that the method can be called concurrently.

UnsafeReleaseAsync(CancellationToken)

Releases the lease ungracefully.

Declaration

public ValueTask<LeaseIdentity> UnsafeReleaseAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseIdentity>

Remarks

It's possible to call AcquireAsync(CancellationToken) method after the current one and get a new lease while the existing owner thinks that the lease is exclusively owned.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.

UnsafeReleaseAsync<TArg>(TArg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>, CancellationToken)

Releases the lease ungracefully.

Declaration

public ValueTask<LeaseIdentity> UnsafeReleaseAsync<TArg>(TArg arg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>> updater, CancellationToken token = default)

Parameters

Type	Name	Description
TArg	arg	The argument to be passed to the metadata updater.
Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>	updater	An idempotent operation to update the metadata on successful acquisition of the lease.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseIdentity>

Type Parameters

Name	Description
TArg	The type of the argument to be passed to the metadata updater.

Remarks

It's possible to call AcquireAsync(CancellationToken) method after the current one and get a new lease while the existing owner thinks that the lease is exclusively owned.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.
ArgumentNullException	updater is null.

UnsafeTryReleaseAsync(CancellationToken)

Tries to release the lease ungracefully.

Declaration

public ValueTask<LeaseIdentity?> UnsafeTryReleaseAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseIdentity?>	Updated lease identity; or null if updated or taken by another process.

Remarks

It's possible to call AcquireAsync(CancellationToken) method after the current one and get a new lease while the existing owner thinks that the lease is exclusively owned.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.

UnsafeTryReleaseAsync<TArg>(TArg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>, CancellationToken)

Tries to release the lease ungracefully.

Declaration

public ValueTask<LeaseIdentity?> UnsafeTryReleaseAsync<TArg>(TArg arg, Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>> updater, CancellationToken token = default)

Parameters

Type	Name	Description
TArg	arg	The argument to be passed to the metadata updater.
Func<TArg, TMetadata, CancellationToken, ValueTask<TMetadata>>	updater	An idempotent operation to update the metadata on successful acquisition of the lease.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<LeaseIdentity?>	Updated lease identity; or null if updated or taken by another process.

Type Parameters

Name	Description
TArg	The type of the argument to be passed to the metadata updater.

Remarks

It's possible to call AcquireAsync(CancellationToken) method after the current one and get a new lease while the existing owner thinks that the lease is exclusively owned.

Exceptions

Type	Condition
ObjectDisposedException	The provider has been disposed.
OperationCanceledException	The operation has been canceled.
ArgumentNullException	updater is null.

Implements

IDisposable

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)

AsyncLockAcquisition.AcquireLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireLockAsync<T>(T, TimeSpan, CancellationToken)

AsyncLockAcquisition.AcquireReadLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireReadLockAsync<T>(T, TimeSpan, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, bool, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, bool, TimeSpan, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, TimeSpan, CancellationToken)

LockAcquisition.AcquireReadLock<T>(T)

LockAcquisition.AcquireReadLock<T>(T, TimeSpan)

LockAcquisition.AcquireUpgradeableReadLock<T>(T)

LockAcquisition.AcquireUpgradeableReadLock<T>(T, TimeSpan)

LockAcquisition.AcquireWriteLock<T>(T)

LockAcquisition.AcquireWriteLock<T>(T, TimeSpan)

See Also

LeaseConsumer