Table of Contents

Struct Leadership

Namespace
Excalibur.Dispatch.LeaderElection
Assembly
Excalibur.Dispatch.LeaderElection.Abstractions.dll

An atomic, point-in-time snapshot of an ILeaderElection instance's leadership state, carrying the fencing token that must be attached to every operation performed during this tenure.

public readonly record struct Leadership : IEquatable<Leadership>
Implements
Inherited Members
Extension Methods

Remarks

Read CurrentLeadership once when the tenure begins and pin the returned value for the duration of the tenure. Because FencingToken and AcquiredAt are captured together in a single atomic read, a consumer never observes a torn combination (for example, a fencing token from one tenure paired with the acquisition time of another).

Constructors

Leadership(long?, DateTimeOffset)

An atomic, point-in-time snapshot of an ILeaderElection instance's leadership state, carrying the fencing token that must be attached to every operation performed during this tenure.

public Leadership(long? FencingToken, DateTimeOffset AcquiredAt)

Parameters

FencingToken long?

The monotonic fencing token minted for this leadership tenure, or null when this tenure carries no fence. A real token is always >= 1; null is the explicit "no fence" signal and is never conflated with a numeric sentinel such as 0. Downstream resources reject any operation presenting a token strictly below the highest token they have already observed; a token at or above that mark is accepted (see IFencedResource, which states the at-or-above relation and why strengthening it to strictly-greater would refuse the live leader from its own second write onward).

What this does and does not guarantee. A fence excludes a superseded tenure only once the successor has actually touched the resource: a superseded tenure's operation cannot be admitted after one of the successor's has been. In the interval between a successor acquiring leadership and its first operation reaching the resource, an operation still in flight from the previous tenure is indistinguishable at the resource from a legitimate one, and both are admitted. No token scheme closes that interval and neither does cancellation, because the resource is the only place that observes both tenures. So the token is necessary and not sufficient: operations that must not take effect twice have to be idempotent as well — presenting a token is not a substitute for that, and a consumer who believes otherwise will omit the one property that covers the gap.

Null means exactly one thing: the deployment configured no fencing. It does NOT mean a fence was configured and no token could be obtained — see the invariant on CurrentLeadership. A consumer may therefore treat a null token as a deliberate opt-out of fencing and admit the operation, which is what makes the two states safe to distinguish by nullability alone.

AcquiredAt DateTimeOffset

The instant at which this leadership tenure began.

Remarks

Read CurrentLeadership once when the tenure begins and pin the returned value for the duration of the tenure. Because FencingToken and AcquiredAt are captured together in a single atomic read, a consumer never observes a torn combination (for example, a fencing token from one tenure paired with the acquisition time of another).

Properties

AcquiredAt

The instant at which this leadership tenure began.

public DateTimeOffset AcquiredAt { get; init; }

Property Value

DateTimeOffset

FencingToken

The monotonic fencing token minted for this leadership tenure, or null when this tenure carries no fence. A real token is always >= 1; null is the explicit "no fence" signal and is never conflated with a numeric sentinel such as 0. Downstream resources reject any operation presenting a token strictly below the highest token they have already observed; a token at or above that mark is accepted (see IFencedResource, which states the at-or-above relation and why strengthening it to strictly-greater would refuse the live leader from its own second write onward).

What this does and does not guarantee. A fence excludes a superseded tenure only once the successor has actually touched the resource: a superseded tenure's operation cannot be admitted after one of the successor's has been. In the interval between a successor acquiring leadership and its first operation reaching the resource, an operation still in flight from the previous tenure is indistinguishable at the resource from a legitimate one, and both are admitted. No token scheme closes that interval and neither does cancellation, because the resource is the only place that observes both tenures. So the token is necessary and not sufficient: operations that must not take effect twice have to be idempotent as well — presenting a token is not a substitute for that, and a consumer who believes otherwise will omit the one property that covers the gap.

Null means exactly one thing: the deployment configured no fencing. It does NOT mean a fence was configured and no token could be obtained — see the invariant on CurrentLeadership. A consumer may therefore treat a null token as a deliberate opt-out of fencing and admit the operation, which is what makes the two states safe to distinguish by nullability alone.

public long? FencingToken { get; init; }

Property Value

long?