Class LeaderElectionClient

Namespace

Azure.Iot.Operations.Services.LeaderElection

Assembly

Azure.Iot.Operations.Services.dll

A client that uses the distributed State Store to perform leader election.

public class LeaderElectionClient : ILeaderElectionClient, IAsyncDisposable

Inheritance

object

LeaderElectionClient

Implements

ILeaderElectionClient

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Once elected, this client will not automatically renew its position by default. This client allows you to opt-in to auto-renew with AutomaticRenewalOptions, though.

When a leader is elected via CampaignAsync(TimeSpan, CampaignRequestOptions?, 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

LeaderElectionClient(ApplicationContext, IMqttPubSubClient, string, string?, IRetryPolicy?)

Construct a new leader election client.

public LeaderElectionClient(ApplicationContext applicationContext, IMqttPubSubClient mqttClient, string leadershipPositionId, string? candidateName = null, IRetryPolicy? retryPolicy = null)

Parameters

applicationContext ApplicationContext

The application context containing shared resources.

mqttClient IMqttPubSubClient

The mqtt client to use for I/O.

leadershipPositionId string

The identifier of the leadership position that this client can campaign for. Each client that will campaign for the same leadership role must share the same value for this parameter.

candidateName string

The name to represent this client. Other clients can look up the current leader's name.

retryPolicy IRetryPolicy

The policy used to add extra wait time after a lease becomes available to give the previous leader priority. If not provided, a default policy will be used LeasedLockClient(IMqttPubSubClient mqttClient, string lockName, IRetryPolicy? retryPolicy = null, string? lockHolderName = null).

Properties

AutomaticRenewalOptions

The options for automatically re-campaigning to be leader at the end of a term as leader. By default, no automatic renewing happens.

public LeaderElectionAutomaticRenewalOptions AutomaticRenewalOptions { get; set; }

Property Value

LeaderElectionAutomaticRenewalOptions

Remarks

These options must be set before calling CampaignAsync(TimeSpan, CampaignRequestOptions?, CancellationToken). Once set, the automatic renewal will begin after the first call to CampaignAsync(TimeSpan, CampaignRequestOptions?, CancellationToken).

Automatic renewal will continue for as long as the leadership position can be re-acquired. If another party acquires the leadership position, then this party's auto-renewal will end. In this case, users should use CampaignAsync(TimeSpan, CampaignRequestOptions?, CancellationToken) to campaign instead to avoid polling.

The result of automatic renewals can be accessed via LastKnownCampaignResult.

CandidateName

The name of this client that is used when campaigning to be leader.

public string CandidateName { get; }

Property Value

string

LastKnownCampaignResult

The result of the most recently run campaign.

public CampaignResponse? LastKnownCampaignResult { get; }

Property Value

CampaignResponse

Remarks

This value captures the result of automatic re-campaigning with AutomaticRenewalOptions.

Methods

CampaignAndUpdateValueAsync(StateStoreKey, Func<StateStoreValue?, StateStoreValue?>, TimeSpan?, CancellationToken)

Block until elected leader, update the value of the state store resource based on its current value, then resign.

public Task CampaignAndUpdateValueAsync(StateStoreKey key, Func<StateStoreValue?, StateStoreValue?> updateValueFunc, TimeSpan? maximumTermLength = null, CancellationToken cancellationToken = default)

Parameters

key StateStoreKey

The state store key whose value will be updated.

updateValueFunc Func<StateStoreValue, StateStoreValue>

The function to execute after elected leader. 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.

maximumTermLength TimeSpan?

The maximum length of time that the client will be leader once elected. Under normal circumstances, this function will resign from the leadership position 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 leadership position can be acquired for before it is released automatically by the service.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

Remarks

This function will always resign from the leadership position if it was elected. Even if cancellation is requested after being elected leader, this function will resign from that position.

CampaignAsync(TimeSpan, CampaignRequestOptions?, CancellationToken)

Await until this client is elected leader or cancellation is requested.

public virtual Task<CampaignResponse> CampaignAsync(TimeSpan electionTerm, CampaignRequestOptions? options = null, CancellationToken cancellationToken = default)

Parameters

electionTerm TimeSpan

How long the client will be leader if elected. This value only has millisecond-level precision.

options CampaignRequestOptions

The optional parameters for this request.

cancellationToken CancellationToken

Cancellation token

Returns

Task<CampaignResponse>

The result of the campaign.

Remarks

Once elected, this client will not automatically renew its position by default. This client allows you to opt-in to auto-renew with AutomaticRenewalOptions, though.

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

disposing bool

Returns

ValueTask

DisposeAsyncCore(bool)

protected virtual ValueTask DisposeAsyncCore(bool disposing)

Parameters

disposing bool

Returns

ValueTask

GetCurrentLeaderAsync(CancellationToken)

Get the name of the current leader.

public virtual Task<GetCurrentLeaderResponse> GetCurrentLeaderAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task<GetCurrentLeaderResponse>

The details about the current leader.

ObserveLeadershipChangesAsync(CancellationToken)

Start receiving notifications when the leader changes.

public virtual Task ObserveLeadershipChangesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task

Remarks

Users who want to watch lock holder change events must first set one or more handlers on LeadershipChangeEventReceivedAsync, then call this function. To stop watching lock holder change events, call UnobserveLeadershipChangesAsync(CancellationToken) and then remove any handlers from LeadershipChangeEventReceivedAsync.

ResignAsync(ResignationRequestOptions?, CancellationToken)

Resign from being the leader.

public virtual Task<ResignationResponse> ResignAsync(ResignationRequestOptions? options = null, CancellationToken cancellationToken = default)

Parameters

options ResignationRequestOptions

The optional parameters for this request.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<ResignationResponse>

The result of the attempted resignation.

TryCampaignAsync(TimeSpan, CampaignRequestOptions?, CancellationToken)

Make a single attempt to campaign to be leader.

public virtual Task<CampaignResponse> TryCampaignAsync(TimeSpan electionTerm, CampaignRequestOptions? options = null, CancellationToken cancellationToken = default)

Parameters

electionTerm TimeSpan

How long the client will be leader if elected. This value only has millisecond-level precision.

options CampaignRequestOptions

The optional parameters for this request.

cancellationToken CancellationToken

Cancellation token

Returns

Task<CampaignResponse>

The result of the campaign.

Remarks

Once elected, this client will not automatically renew its position by default. This client allows you to opt-in to auto-renew with AutomaticRenewalOptions, though.

UnobserveLeadershipChangesAsync(CancellationToken)

Stop receiving notifications when the leader changes.

public virtual Task UnobserveLeadershipChangesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task

Remarks

Users who want to watch lock holder change events must first set one or more handlers on LeadershipChangeEventReceivedAsync, then call ObserveLeadershipChangesAsync(ObserveLeadershipChangesRequestOptions?, CancellationToken). To stop watching lock holder change events, call this function and then remove any handlers from LeadershipChangeEventReceivedAsync.

Events

LeadershipChangeEventReceivedAsync

The callback that executes whenever the current leader changes.

public event Func<object?, LeadershipChangeEventArgs, Task>? LeadershipChangeEventReceivedAsync

Event Type

Func<object, LeadershipChangeEventArgs, Task>

Remarks

Users who want to watch leadership change events must first set this callback, then call ObserveLeadershipChangesAsync(ObserveLeadershipChangesRequestOptions?, CancellationToken). To stop watching leadership change events, call UnobserveLeadershipChangesAsync(CancellationToken) and then remove any handlers from this object.