Interface ILeaderElectionClient

Namespace

Azure.Iot.Operations.Services.LeaderElection

Assembly

Azure.Iot.Operations.Services.dll

The interface for clients that perform leader election.

public interface ILeaderElectionClient : IAsyncDisposable

Inherited Members

IAsyncDisposable.DisposeAsync()

Remarks

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

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.

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.

string CandidateName { get; }

Property Value

string

LastKnownCampaignResult

The result of the most recently run campaign.

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.

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.

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.

GetCurrentLeaderAsync(CancellationToken)

Get the name of the current leader.

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.

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.

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.

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.

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.

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.