Class LeasedLockClient
- Namespace
- Azure.Iot.Operations.Services.LeasedLock
- Assembly
- Azure.Iot.Operations.Services.dll
A client to facilitate leased lock operations on a specific, provided lock name.
public class LeasedLockClient : IAsyncDisposable- Inheritance
-
LeasedLockClient
- Implements
- Inherited Members
Remarks
Once acquired, a lock will not be automatically renewed by default. This client allows you to opt-in to auto-renew with AutomaticRenewalOptions, though.
When a lock is granted via AcquireLockAsync(TimeSpan, AcquireLockRequestOptions?, CancellationToken), the service will respond with a fencing token via FencingToken. This fencing token allows for State Store set/delete operations on shared resources without risk of race conditions.
Constructors
LeasedLockClient(ApplicationContext, IMqttPubSubClient, string, string?, IRetryPolicy?)
Construct a new leased lock client.
public LeasedLockClient(ApplicationContext applicationContext, IMqttPubSubClient mqttClient, string lockName, string? lockHolderName = null, IRetryPolicy? retryPolicy = null)Parameters
applicationContextApplicationContextThe application context containing shared resources.
mqttClientIMqttPubSubClientThe client to use for I/O operations.
lockNamestringThe name of the lock to acquire/release.
lockHolderNamestringThe name for this client that will hold a lock. Other processes will be able to check which client holds a lock by name. By default, this is set to the MQTT client ID.
retryPolicyIRetryPolicyThe policy used to add extra wait time after leas available to acquire.
LeasedLockClient(IStateStoreClient, string, string, IRetryPolicy?)
public LeasedLockClient(IStateStoreClient stateStoreClient, string lockName, string lockHolderName, IRetryPolicy? retryPolicy = null)Parameters
stateStoreClientIStateStoreClientlockNamestringlockHolderNamestringretryPolicyIRetryPolicy
Properties
AutomaticRenewalOptions
The options for automatically re-acquiring a lock before the previous lease expires. By default, no automatic re-acquiring happens.
public LeasedLockAutomaticRenewalOptions AutomaticRenewalOptions { get; set; }Property Value
Remarks
These options must be set before calling AcquireLockAsync(TimeSpan, AcquireLockRequestOptions?, CancellationToken). Once set, the automatic renewal will begin after the first call to AcquireLockAsync(TimeSpan, AcquireLockRequestOptions?, CancellationToken).
Automatic renewal will continue for as long as the lock can be re-acquired. If another party acquires the lock, then this party's auto-renewal will end. In this case, users should use AcquireLockAsync(TimeSpan, AcquireLockRequestOptions?, CancellationToken) to acquire the lock instead to avoid polling.
The result of automatic renewals can be accessed via MostRecentAcquireLockResponse.
LockHolderName
The name this client uses when trying to acquire the leased lock.
public string LockHolderName { get; }Property Value
MostRecentAcquireLockResponse
The result of the most recent attempt at acquiring the lock.
public AcquireLockResponse? MostRecentAcquireLockResponse { get; }Property Value
Remarks
This value captures the result of automatic re-renewing of the lock with AutomaticRenewalOptions.
Methods
AcquireLockAndUpdateValueAsync(StateStoreKey, Func<StateStoreValue?, StateStoreValue?>, TimeSpan?, CancellationToken)
Block until the lock is acquired, update the value of the state store resource based on its current value, then release the lock.
public Task AcquireLockAndUpdateValueAsync(StateStoreKey key, Func<StateStoreValue?, StateStoreValue?> updateValueFunc, TimeSpan? maximumLeaseDuration = null, CancellationToken cancellationToken = default)Parameters
keyStateStoreKeyThe state store key whose value will be updated.
updateValueFuncFunc<StateStoreValue, StateStoreValue>The function to execute after the lock is acquired. The parameter of this function contains the current value of the state store key. The return value of this function is the new value that you wish the state store key to have.
maximumLeaseDurationTimeSpan?The maximum length of time that the client will lease the lock for once acquired. Under normal circumstances, this function will release the lock after updating the value of the shared resource, but it is possible that this client is interrupted or encounters a fatal exception. By setting a low value for this field, you limit how long the lock can be acquired for before it is released automatically by the service.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
This function will always release the lock if it was acquired. Even if cancellation is requested when the lock is acquired, this function will release the lock.
AcquireLockAsync(TimeSpan, AcquireLockRequestOptions?, CancellationToken)
Await until this client has acquired the lock or cancellation is requested.
public virtual Task<AcquireLockResponse> AcquireLockAsync(TimeSpan leaseDuration, AcquireLockRequestOptions? options = null, CancellationToken cancellationToken = default)Parameters
leaseDurationTimeSpanThe duration for which the lock will be held if the lock is acquired This value only has millisecond-level precision.
optionsAcquireLockRequestOptionsThe lock request options.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<AcquireLockResponse>
The service response object containing the fencing token if the lock was successfully acquired.
DisposeAsync()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.
public ValueTask DisposeAsync()Returns
- ValueTask
A task that represents the asynchronous dispose operation.
DisposeAsync(bool)
public ValueTask DisposeAsync(bool disposing)Parameters
disposingbool
Returns
DisposeAsyncCore(bool)
protected virtual ValueTask DisposeAsyncCore(bool disposing)Parameters
disposingbool
Returns
GetLockHolderAsync(CancellationToken)
Get the current holder of the lock.
public virtual Task<GetLockHolderResponse> GetLockHolderAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<GetLockHolderResponse>
The details about the current holder of the lock.
Remarks
When acquired, a lock has a value assigned to it which follows the format: {lockHolderName}:{sessionId}. This function will return this value so that the owner of the lock can be identified by one or both of these fields.
ObserveLockAsync(CancellationToken)
Start receiving notifications when the lock holder changes for this leased lock.
public virtual Task ObserveLockAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
Users who want to watch lock holder change events must first set one or more handlers on LockChangeEventReceivedAsync, then call this function. To stop watching lock holder change events, call UnobserveLockAsync(CancellationToken) and then remove any handlers from LockChangeEventReceivedAsync.
ReleaseLockAsync(ReleaseLockRequestOptions?, CancellationToken)
Attempt to release a lock with the provided name.
public virtual Task<ReleaseLockResponse> ReleaseLockAsync(ReleaseLockRequestOptions? options = null, CancellationToken cancellationToken = default)Parameters
optionsReleaseLockRequestOptionscancellationTokenCancellationToken
Returns
- Task<ReleaseLockResponse>
The response to the request.
TryAcquireLockAsync(TimeSpan, AcquireLockRequestOptions?, CancellationToken)
Attempt to acquire a lock with the provided name.
public virtual Task<AcquireLockResponse> TryAcquireLockAsync(TimeSpan leaseDuration, AcquireLockRequestOptions? options = null, CancellationToken cancellationToken = default)Parameters
leaseDurationTimeSpanThe duration for which the lock will be held. This value only has millisecond-level precision.
optionsAcquireLockRequestOptionsThe lock request options.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<AcquireLockResponse>
AcquireLockResponse object with result (and fencing token if the lock was successfully acquired.)
Remarks
Once acquired, a lock will not be automatically renewed by default. This client allows you to opt-in to auto-renew with AutomaticRenewalOptions, though.
When acquired, a lock has a value assigned to it which follows either the format
{lockHolderName}:{sessionId} if a sessionId is provided by options or
just {lockHolderName} if no sessionId is provided. The lock holder name is chosen
when constructing this client and a sessionId can be chosen (or omitted, by default)
each attempt to acquire a lock.
UnobserveLockAsync(CancellationToken)
Stop receiving notifications when the lock holder changes.
public virtual Task UnobserveLockAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
Users who want to watch lock holder change events must first set one or more handlers on LockChangeEventReceivedAsync, then call ObserveLockAsync(ObserveLockRequestOptions?, CancellationToken). To stop watching lock holder change events, call this function and then remove any handlers from LockChangeEventReceivedAsync.
Events
LockChangeEventReceivedAsync
The callback that executes whenever the current holder of the lock changes.
public event Func<object?, LockChangeEventArgs, Task>? LockChangeEventReceivedAsyncEvent Type
Remarks
Users who want to watch lock holder change events must first set this callback, then call ObserveLockAsync(ObserveLockRequestOptions?, CancellationToken) To stop watching lock holder change events, call UnobserveLockAsync(CancellationToken) and then remove any handlers from this object.