Class RaftCluster<TMember>

public abstract class RaftCluster<TMember> : Disposable, IDisposable, IUnresponsiveClusterMemberRemovalSupport, IStandbyModeSupport, IRaftCluster, IReplicationCluster<IRaftLogEntry>, IReplicationCluster, ICluster, IPeerMesh<IClusterMember>, IPeerMesh<IRaftClusterMember>, IPeerMesh, IAsyncDisposable where TMember : class, IRaftClusterMember, IDisposable

Type Parameters

Name	Description
TMember	The type implementing communication details with remote nodes.

Constructors

| Edit this page View Source

RaftCluster(IClusterMemberConfiguration)

Initializes a new cluster manager for the local node.

Declaration

protected RaftCluster(IClusterMemberConfiguration config)

Parameters

Type	Name	Description
IClusterMemberConfiguration	config	The configuration of the local node.

| Edit this page View Source

RaftCluster(IClusterMemberConfiguration, in TagList)

Initializes a new cluster manager for the local node.

Declaration

[CLSCompliant(false)]
protected RaftCluster(IClusterMemberConfiguration config, in TagList measurementTags)

Parameters

Type	Name	Description
IClusterMemberConfiguration	config	The configuration of the local node.
TagList	measurementTags	A tags to be attached to each performance measurement.

Properties

| Edit this page View Source

AuditTrail

Associates audit trail with the current instance.

Declaration

public IPersistentState AuditTrail { get; set; }

Property Value

Type	Description
IPersistentState

Exceptions

Type	Condition
ArgumentNullException	`value` is null.

| Edit this page View Source

ConfigurationStorage

Gets configuration storage.

Declaration

protected abstract IClusterConfigurationStorage ConfigurationStorage { get; }

Property Value

Type	Description
IClusterConfigurationStorage

| Edit this page View Source

ConsensusToken

Gets a token that remains non-canceled while the local node is a part of the majority of the cluster and has communication with the leader.

Declaration

public CancellationToken ConsensusToken { get; }

Property Value

Type	Description
CancellationToken

Remarks

The token moves to canceled state if the current node upgrades to the candidate state or loses connection with the leader.

| Edit this page View Source

ElectionTimeout

Gets election timeout used by the local member.

Declaration

public TimeSpan ElectionTimeout { get; }

Property Value

Type	Description
TimeSpan

| Edit this page View Source

EndPointComparer

Gets the comparer for EndPoint type.

Declaration

protected IEqualityComparer<EndPoint> EndPointComparer { get; }

Property Value

Type	Description
IEqualityComparer<EndPoint>

| Edit this page View Source

FailureDetectorFactory

Gets or sets failure detector to be used by the leader node to detect and remove unresponsive followers.

Declaration

public Func<TimeSpan, TMember, IFailureDetector>? FailureDetectorFactory { get; init; }

Property Value

Type	Description
Func<TimeSpan, TMember, IFailureDetector>

| Edit this page View Source

Leader

Gets leader of the cluster.

Declaration

public TMember? Leader { get; }

Property Value

Type	Description
TMember

| Edit this page View Source

LeadershipToken

Gets the token that can be used to track leader state.

Declaration

public CancellationToken LeadershipToken { get; }

Property Value

Type	Description
CancellationToken

Remarks

The token moves to canceled state if the current node downgrades to the follower state.

| Edit this page View Source

LifecycleToken

Gets token that can be used for all internal asynchronous operations.

Declaration

protected CancellationToken LifecycleToken { get; }

Property Value

Type	Description
CancellationToken

| Edit this page View Source

Logger

Gets logger used by this object.

Declaration

[CLSCompliant(false)]
protected virtual ILogger Logger { get; }

Property Value

Type	Description
ILogger

| Edit this page View Source

Members

Gets members of Raft-based cluster.

Declaration

public IReadOnlyCollection<TMember> Members { get; }

Property Value

Type	Description
IReadOnlyCollection<TMember>	A collection of cluster member.

| Edit this page View Source

Readiness

Represents a task indicating that the current node is ready to serve requests.

Declaration

public Task Readiness { get; }

Property Value

Type	Description
Task

| Edit this page View Source

Standby

Gets a value indicating that the local member cannot be elected as cluster leader.

Declaration

public bool Standby { get; }

Property Value

Type	Description
bool

| Edit this page View Source

Term

Gets Term value maintained by local member.

Declaration

public long Term { get; }

Property Value

Type	Description
long

Methods

| Edit this page View Source

AddMemberAsync(TMember, CancellationToken)

Adds a new member to the collection of members visible by the current node.

Declaration

public ValueTask<bool> AddMemberAsync(TMember member, CancellationToken token)

Parameters

Type	Name	Description
TMember	member	The member to add.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<bool>	true if the member is addedd successfully; false if the member is already in the list.

Remarks

This method is exposed to be called by ActiveConfigurationChanged handler.

| Edit this page View Source

AddMemberAsync<TAddress>(TMember, int, IClusterConfigurationStorage<TAddress>, Func<TMember, TAddress>, CancellationToken)

Announces a new member in the cluster.

Declaration

protected Task<bool> AddMemberAsync<TAddress>(TMember member, int rounds, IClusterConfigurationStorage<TAddress> configurationStorage, Func<TMember, TAddress> addressProvider, CancellationToken token = default) where TAddress : notnull

Parameters

Type	Name	Description
TMember	member	The cluster member client used to catch up its state.
int	rounds	The number of warmup rounds.
IClusterConfigurationStorage<TAddress>	configurationStorage	The configuration storage.
Func<TMember, TAddress>	addressProvider	The delegate that allows to get the address of the member.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
Task<bool>	true if the node has been added to the cluster successfully; false if the node rejects the replication or the address of the node cannot be committed.

Type Parameters

Name	Description
TAddress	The type of the member address.

Exceptions

Type	Condition
ArgumentOutOfRangeException	`rounds` is less than or equal to zero.
OperationCanceledException	The operation has been canceled or the cluster elects a new leader.
InvalidOperationException	The current node is not a leader.
RaftCluster<TMember>.ConcurrentMembershipModificationException	The method is called concurrently.

| Edit this page View Source

AppendEntriesAsync<TEntry>(ClusterMemberId, long, ILogEntryProducer<TEntry>, long, long, long, IClusterConfiguration, bool, CancellationToken)

Handles AppendEntries message received from remote cluster member.

Declaration

protected ValueTask<Result<HeartbeatResult>> AppendEntriesAsync<TEntry>(ClusterMemberId sender, long senderTerm, ILogEntryProducer<TEntry> entries, long prevLogIndex, long prevLogTerm, long commitIndex, IClusterConfiguration config, bool applyConfig, CancellationToken token) where TEntry : IRaftLogEntry

Parameters

Type	Name	Description
ClusterMemberId	sender	The sender of the replica message.
long	senderTerm	Term value provided by Heartbeat message sender.
ILogEntryProducer<TEntry>	entries	The stateful function that provides entries to be committed locally.
long	prevLogIndex	Index of log entry immediately preceding new ones.
long	prevLogTerm	Term of `prevLogIndex` entry.
long	commitIndex	The last entry known to be committed on the sender side.
IClusterConfiguration	config	The list of cluster members.
bool	applyConfig	true to inform that the receiver must apply previously proposed configuration; false to propose a new configuration.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<Result<HeartbeatResult>>	The processing result.

Type Parameters

Name	Description
TEntry	The actual type of the log entry returned by the supplier.

| Edit this page View Source

ApplyReadBarrierAsync(CancellationToken)

Ensures linearizable read from underlying state machine.

Declaration

public ValueTask ApplyReadBarrierAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask	The task representing asynchronous result.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.

| Edit this page View Source

DetectLocalMemberAsync(TMember, CancellationToken)

Determines whether the specified candidate represents a local node.

Declaration

protected abstract ValueTask<bool> DetectLocalMemberAsync(TMember candidate, CancellationToken token)

Parameters

Type	Name	Description
TMember	candidate	The candidate to check.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<bool>	true if `candidate` represents a local node; otherwise, false.

| Edit this page View Source

Dispose(bool)

Releases managed and unmanaged resources associated with this object.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	true if called from Dispose(); false if called from finalizer ~Disposable().

Overrides

Disposable.Dispose(bool)

| Edit this page View Source

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

Declaration

public ValueTask DisposeAsync()

Returns

Type	Description
ValueTask	A task that represents the asynchronous dispose operation.

| Edit this page View Source

DisposeAsyncCore()

Releases managed resources associated with this object asynchronously.

Declaration

protected override ValueTask DisposeAsyncCore()

Returns

Type	Description
ValueTask	The task representing asynchronous execution of this method.

Overrides

Disposable.DisposeAsyncCore()

Remarks

This method makes sense only if derived class implements IAsyncDisposable interface.

| Edit this page View Source

EnableStandbyModeAsync(CancellationToken)

Suspends any transition over Raft states.

Declaration

public ValueTask<bool> EnableStandbyModeAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<bool>	true if any further state transitions are suspended successfully because the local member is in Follower state; false if operation fails because state transition is already suspended or the local member is not in Follower state.

Remarks

This method completes successfully only if the local member is in Follower state.

Exceptions

Type	Condition
ObjectDisposedException	This object has been disposed.

| Edit this page View Source

ForceReplicationAsync(CancellationToken)

Forces replication.

Declaration

public ValueTask ForceReplicationAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel waiting.

Returns

Type	Description
ValueTask	The task representing asynchronous result.

Remarks

This methods waits for responses from all available cluster members, not from the majority of them.

Exceptions

Type	Condition
InvalidOperationException	The local cluster member is not a leader.
OperationCanceledException	The operation has been canceled.

| Edit this page View Source

InstallSnapshotAsync<TSnapshot>(ClusterMemberId, long, TSnapshot, long, CancellationToken)

Handles InstallSnapshot message received from remote cluster member.

Declaration

protected ValueTask<Result<HeartbeatResult>> InstallSnapshotAsync<TSnapshot>(ClusterMemberId sender, long senderTerm, TSnapshot snapshot, long snapshotIndex, CancellationToken token) where TSnapshot : IRaftLogEntry

Parameters

Type	Name	Description
ClusterMemberId	sender	The sender of the snapshot message.
long	senderTerm	Term value provided by InstallSnapshot message sender.
TSnapshot	snapshot	The snapshot to be installed into local audit trail.
long	snapshotIndex	The index of the last log entry included in the snapshot.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<Result<HeartbeatResult>>	true if snapshot is installed successfully; null if snapshot is outdated.

Type Parameters

Name	Description
TSnapshot	The type of snapshot record.

| Edit this page View Source

PreVoteAsync(ClusterMemberId, long, long, long, CancellationToken)

Receives preliminary vote from the potential Candidate in the cluster.

Declaration

protected ValueTask<Result<PreVoteResult>> PreVoteAsync(ClusterMemberId sender, long nextTerm, long lastLogIndex, long lastLogTerm, CancellationToken token)

Parameters

Type	Name	Description
ClusterMemberId	sender	The sender of the replica message.
long	nextTerm	Caller's current term + 1.
long	lastLogIndex	Index of candidate's last log entry.
long	lastLogTerm	Term of candidate's last log entry.
CancellationToken	token	The token that can be used to cancel asynchronous operation.

Returns

Type	Description
ValueTask<Result<PreVoteResult>>	Pre-vote result received from the member.

| Edit this page View Source

RemoveMemberAsync(ClusterMemberId, CancellationToken)

Removes the member from the collection of members visible by the current node.

Declaration

public ValueTask<TMember?> RemoveMemberAsync(ClusterMemberId id, CancellationToken token)

Parameters

Type	Name	Description
ClusterMemberId	id	The identifier of the member.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<TMember>	The removed member.

Remarks

This method is exposed to be called by ActiveConfigurationChanged handler.

| Edit this page View Source

RemoveMemberAsync<TAddress>(ClusterMemberId, IClusterConfigurationStorage<TAddress>, Func<TMember, TAddress>, CancellationToken)

Removes the member from the cluster.

Declaration

protected Task<bool> RemoveMemberAsync<TAddress>(ClusterMemberId id, IClusterConfigurationStorage<TAddress> configurationStorage, Func<TMember, TAddress> addressProvider, CancellationToken token = default) where TAddress : notnull

Parameters

Type	Name	Description
ClusterMemberId	id	The cluster member to remove.
IClusterConfigurationStorage<TAddress>	configurationStorage	The configuration storage.
Func<TMember, TAddress>	addressProvider	The delegate that allows to get the address of the member.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
Task<bool>	true if the node has been removed from the cluster successfully; false if the node rejects the replication or the address of the node cannot be committed.

Type Parameters

Name	Description
TAddress	The type of the member address.

Exceptions

Type	Condition
InvalidOperationException	The current node is not a leader.
OperationCanceledException	The operation has been canceled or the cluster elects a new leader.
RaftCluster<TMember>.ConcurrentMembershipModificationException	The method is called concurrently.

| Edit this page View Source

ReplicateAsync<TEntry>(TEntry, CancellationToken)

Appends a new log entry and ensures that it is replicated and committed.

Declaration

public ValueTask<bool> ReplicateAsync<TEntry>(TEntry entry, CancellationToken token) where TEntry : IRaftLogEntry

Parameters

Type	Name	Description
TEntry	entry	The log entry to be added.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<bool>	true if the appended log entry has been committed by the majority of nodes; false if retry is required.

Type Parameters

Name	Description
TEntry	The type of the log entry.

Exceptions

Type	Condition
ObjectDisposedException	This object has been disposed.
InvalidOperationException	The current node is not a leader.
OperationCanceledException	The operation has been canceled.

| Edit this page View Source

ResignAsync(CancellationToken)

Revokes leadership of the local node.

Declaration

protected ValueTask<bool> ResignAsync(CancellationToken token)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<bool>	true, if leadership is revoked successfully; otherwise, false.

| Edit this page View Source

RevertToNormalModeAsync(CancellationToken)

Turns this node into the regular state when the node can be elected as leader.

Declaration

public ValueTask<bool> RevertToNormalModeAsync(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<bool>	true if state transition is resumed successfully; false if state transition was not suspended.

Exceptions

Type	Condition
ObjectDisposedException	This object has been disposed.

| Edit this page View Source

StartAsync(CancellationToken)

Starts serving local member.

Declaration

public virtual Task StartAsync(CancellationToken token)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel the initialization process.

Returns

Type	Description
Task	The task representing asynchronous execution of the method.

StartFollowing()

Starts Follower timer.

Declaration

protected void StartFollowing()

| Edit this page View Source

StopAsync(CancellationToken)

Stops serving local member.

Declaration

public virtual Task StopAsync(CancellationToken token)

Parameters

Type	Name	Description
CancellationToken	token	The token that can be used to cancel shutdown process.

Returns

Type	Description
Task	The task representing asynchronous execution of the method.

| Edit this page View Source

SynchronizeAsync(long, CancellationToken)

Processes SynchronizeAsync(long, CancellationToken) request.

Declaration

protected ValueTask<long?> SynchronizeAsync(long commitIndex, CancellationToken token)

Parameters

Type	Name	Description
long	commitIndex	The index of the last committed log entry on the sender side.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<long?>	The index of the last committed log entry known by the leader.

| Edit this page View Source

TryGetLeaseToken(out CancellationToken)

Tries to get the lease that can be used to perform the read with linearizability guarantees.

Declaration

public bool TryGetLeaseToken(out CancellationToken token)

Parameters

Type	Name	Description
CancellationToken	token	The token representing lease.

Returns

Type	Description
bool	true if the current node is leader; otherwise, false.

| Edit this page View Source

TryGetMember(ClusterMemberId)

Gets the member by its identifier.

Declaration

protected TMember? TryGetMember(ClusterMemberId id)

Parameters

Type	Name	Description
ClusterMemberId	id	The identifier of the cluster member.

Returns

Type	Description
TMember	true if member found; otherwise, false.

| Edit this page View Source

UnavailableMemberDetected(TMember, CancellationToken)

Notifies that the member is unavailable.

Declaration

protected virtual ValueTask UnavailableMemberDetected(TMember member, CancellationToken token)

Parameters

Type	Name	Description
TMember	member	The member that is considered as unavailable.
CancellationToken	token	The token associated with LeadershipToken that identifies the leader state at the time of detection.

Returns

Type	Description
ValueTask	The task representing asynchronous result.

Remarks

It's an infrastructure method that can be used to remove unavailable member from the cluster configuration at the leader side.

| Edit this page View Source

VoteAsync(ClusterMemberId, long, long, long, CancellationToken)

Votes for the new candidate.

Declaration

protected ValueTask<Result<bool>> VoteAsync(ClusterMemberId sender, long senderTerm, long lastLogIndex, long lastLogTerm, CancellationToken token)

Parameters

Type	Name	Description
ClusterMemberId	sender	The vote sender.
long	senderTerm	Term value provided by sender of the request.
long	lastLogIndex	Index of candidate's last log entry.
long	lastLogTerm	Term of candidate's last log entry.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<Result<bool>>	true if local node accepts new leader in the cluster; otherwise, false.

| Edit this page View Source

WaitForLeaderAsync(TimeSpan, CancellationToken)

Waits for the leader election asynchronously.

Declaration

public Task<TMember> WaitForLeaderAsync(TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
TimeSpan	timeout	The time to wait; or InfiniteTimeSpan.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
Task<TMember>	The elected leader.

Exceptions

Type	Condition
TimeoutException	The operation is timed out.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The local node is disposed.

| Edit this page View Source

WaitForLeadershipAsync(TimeSpan, CancellationToken)

Waits until the local node is elected as the leader.

Declaration

public ValueTask<CancellationToken> WaitForLeadershipAsync(TimeSpan timeout, CancellationToken token = default)

Parameters

Type	Name	Description
TimeSpan	timeout	The time to wait; or InfiniteTimeSpan.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<CancellationToken>	The leadership token.

Exceptions

Type	Condition
TimeoutException	The operation is timed out.
OperationCanceledException	The operation has been canceled.
ObjectDisposedException	The local node is disposed.

Events

| Edit this page View Source

LeaderChanged

An event raised when leader has been changed.

Declaration

public event Action<RaftCluster<TMember>, TMember?> LeaderChanged

Event Type

Type	Description
Action<RaftCluster<TMember>, TMember>

| Edit this page View Source

MemberAdded

An event raised when new cluster member is detected.

Declaration

public event Action<RaftCluster<TMember>, RaftClusterMemberEventArgs<TMember>> MemberAdded

Event Type

Type	Description
Action<RaftCluster<TMember>, RaftClusterMemberEventArgs<TMember>>

| Edit this page View Source

MemberRemoved

An event raised when cluster member is removed gracefully.

Declaration

public event Action<RaftCluster<TMember>, RaftClusterMemberEventArgs<TMember>> MemberRemoved

Event Type

Type	Description
Action<RaftCluster<TMember>, RaftClusterMemberEventArgs<TMember>>

| Edit this page View Source

ReplicationCompleted

Represents an event raised when the local node completes its replication with another node.

Declaration

public event Action<RaftCluster<TMember>, TMember> ReplicationCompleted

Event Type

Type	Description
Action<RaftCluster<TMember>, TMember>

Implements

IDisposable

IUnresponsiveClusterMemberRemovalSupport

IStandbyModeSupport

IRaftCluster

IReplicationCluster<TEntry>

IReplicationCluster

ICluster

IPeerMesh<TPeer>

IPeerMesh

IAsyncDisposable

Extension Methods

RaftClusterExtensions.ReplicateAsync(IRaftCluster, ReadOnlyMemory<byte>, object?, CancellationToken)

RaftClusterExtensions.ReplicateAsync<T>(IRaftCluster, T, object?, CancellationToken)

RaftClusterExtensions.ReplicateJsonAsync<T>(IRaftCluster, T, object?, CancellationToken)

BasicExtensions.As<T>(T)

BasicExtensions.GetUserData<T>(T)

BasicExtensions.IsBetween<T, TLowerBound, TUpperBound>(T, TLowerBound, TUpperBound)

BasicExtensions.IsOneOf<T>(T, ReadOnlySpan<T>)

ExpressionBuilder.Const<T>(T)

AsyncLockAcquisition.AcquireLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireLockAsync<T>(T, TimeSpan, CancellationToken)

AsyncLockAcquisition.AcquireReadLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireReadLockAsync<T>(T, TimeSpan, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, bool, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, bool, TimeSpan, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, TimeSpan, CancellationToken)

LockAcquisition.AcquireReadLock<T>(T)

LockAcquisition.AcquireReadLock<T>(T, TimeSpan)

LockAcquisition.AcquireUpgradeableReadLock<T>(T)

LockAcquisition.AcquireUpgradeableReadLock<T>(T, TimeSpan)

LockAcquisition.AcquireWriteLock<T>(T)

LockAcquisition.AcquireWriteLock<T>(T, TimeSpan)