Class Lock
Namespace: Consul
Assembly: Consul.dll
Lock is used to implement client-side leader election. It is follows the algorithm as described here: https://consul.io/docs/guides/leader-election.html.
public class Lock : IDistributedLock
Inheritance
Implements
Inherited Members
object.Equals(object) , object.Equals(object, object) , object.GetHashCode() , object.GetType() , object.MemberwiseClone() , object.ReferenceEquals(object, object) , object.ToString()
Fields
DefaultLockRetryTime
DefaultLockRetryTime is how long we wait after a failed lock acquisition before attempting to do the lock again. This is so that once a lock-delay is in effect, we do not hot loop retrying the acquisition.
public static readonly TimeSpan DefaultLockRetryTime
Field Value
DefaultLockWaitTime
DefaultLockWaitTime is how long we block for at a time to check if lock acquisition is possible. This affects the minimum time it takes to cancel a Lock acquisition.
public static readonly TimeSpan DefaultLockWaitTime
Field Value
DefaultMonitorRetryTime
DefaultMonitorRetryTime is how long we wait after a failed monitor check of a lock (500 response code). This allows the monitor to ride out brief periods of unavailability, subject to the MonitorRetries setting in the lock options which is by default set to 0, disabling this feature.
public static readonly TimeSpan DefaultMonitorRetryTime
Field Value
Properties
IsHeld
If the lock is held or not. Users of the Lock object should check the IsHeld property before entering the critical section of their code, e.g. in a "while (myLock.IsHeld) {criticalsection}" block. Calls to IsHeld are syncronized across threads using a lock, so multiple threads sharing a single Consul Lock will queue up reading the IsHeld property of the lock.
public bool IsHeld { get; }
Property Value
Methods
Acquire()
Lock attempts to acquire the lock and blocks while doing so. Not providing a CancellationToken means the thread can block indefinitely until the lock is acquired. There is no notification that the lock has been lost, but it may be closed at any time due to session invalidation, communication errors, operator intervention, etc. It is NOT safe to assume that the lock is held until Unlock() unless the Session is specifically created without any associated health checks. Users of the Lock object should check the IsHeld property before entering the critical section of their code, e.g. in a "while (myLock.IsHeld) {criticalsection}" block. By default Consul sessions prefer liveness over safety and an application must be able to handle the lock being lost.
public Task<CancellationToken> Acquire()
Returns
Acquire(CancellationToken)
Lock attempts to acquire the lock and blocks while doing so. Providing a CancellationToken can be used to abort the lock attempt. There is no notification that the lock has been lost, but IsHeld may be set to False at any time due to session invalidation, communication errors, operator intervention, etc. It is NOT safe to assume that the lock is held until Unlock() unless the Session is specifically created without any associated health checks. Users of the Lock object should check the IsHeld property before entering the critical section of their code, e.g. in a "while (myLock.IsHeld) {criticalsection}" block. By default Consul sessions prefer liveness over safety and an application must be able to handle the lock being lost.
public Task<CancellationToken> Acquire(CancellationToken ct)
Parameters
The cancellation token to cancel lock acquisition
Returns
Destroy(CancellationToken)
Destroy is used to cleanup the lock entry. It is not necessary to invoke. It will fail if the lock is in use.
public Task Destroy(CancellationToken ct = default)
Parameters
Returns
Release(CancellationToken)
Unlock released the lock. It is an error to call this if the lock is not currently held.
public Task Release(CancellationToken ct = default)