Class PersistentState

Represents general purpose persistent audit trail compatible with Raft algorithm.

Inheritance

Object

Disposable

PersistentState

Implements

IDisposable

IPersistentState

Log.IAuditTrail<IRaftLogEntry>

IAsyncDisposable

Inherited Members

Disposable.IsDisposed

Disposable.ThrowIfDisposed()

Disposable.DisposedTask

Disposable.GetDisposedTask<T>()

Disposable.TrySetDisposedException<T>(TaskCompletionSource<T>)

Disposable.Dispose()

Disposable.QueueDispose(IDisposable)

Disposable.Dispose(IEnumerable<IDisposable>)

Disposable.DisposeAsync(IEnumerable<IAsyncDisposable>)

Disposable.Dispose(IDisposable[])

Disposable.DisposeAsync(IAsyncDisposable[])

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

Namespace: DotNext.Net.Cluster.Consensus.Raft

Assembly: DotNext.Net.Cluster.dll

Syntax

public class PersistentState : Disposable, IDisposable, IPersistentState, Log.IAuditTrail<IRaftLogEntry>, IAsyncDisposable

Remarks

The layout of of the audit trail file system:

node.state	file containing internal state of Raft node
<partition>	file containing log partition with log records
snapshot	file containing snapshot

The audit trail supports log compaction. However, it doesn't know how to interpret and reduce log records during compaction. To do that, you can override CreateSnapshotBuilder() method and implement state machine logic.

Constructors

PersistentState(DirectoryInfo, Int32, PersistentState.Options)

Initializes a new persistent audit trail.

Declaration

public PersistentState(DirectoryInfo path, int recordsPerPartition, PersistentState.Options configuration = null)

Parameters

Type	Name	Description
DirectoryInfo	path	The path to the folder to be used by audit trail.
Int32	recordsPerPartition	The maximum number of log entries that can be stored in the single file called partition.
PersistentState.Options	configuration	The configuration of the persistent audit trail.

Exceptions

Type	Condition
ArgumentOutOfRangeException	recordsPerPartition is less than 2.

PersistentState(String, Int32, PersistentState.Options)

Initializes a new persistent audit trail.

Declaration

public PersistentState(string path, int recordsPerPartition, PersistentState.Options configuration = null)

Parameters

Type	Name	Description
String	path	The path to the folder to be used by audit trail.
Int32	recordsPerPartition	The maximum number of log entries that can be stored in the single file called partition.
PersistentState.Options	configuration	The configuration of the persistent audit trail.

Exceptions

Type	Condition
ArgumentOutOfRangeException	recordsPerPartition is less than 2.

Properties

Buffer

Gets the buffer that can be used to perform I/O operations.

Declaration

protected Memory<byte> Buffer { get; }

Property Value

Type	Description
Memory<Byte>

Remarks

The buffer cannot be used concurrently. Access to it should be synchronized using AcquireWriteLockAsync(CancellationToken) method. However, synchronization is not needed inside of ApplyAsync(PersistentState.LogEntry) method.

Term

Gets the current term.

Declaration

public long Term { get; }

Property Value

Type	Description
Int64

Methods

AcquireWriteLockAsync(CancellationToken)

Acquires write lock so the caller has exclusive rights to write the entries.

Declaration

public Task<PersistentState.WriteLockToken> AcquireWriteLockAsync(CancellationToken token)

Parameters

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

Returns

Type	Description
Task<PersistentState.WriteLockToken>	The token representing acquired write lock.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.

AcquireWriteLockAsync(TimeSpan, CancellationToken)

Acquires write lock so the caller has exclusive rights to write the entries.

Declaration

public Task<PersistentState.WriteLockToken> AcquireWriteLockAsync(TimeSpan timeout, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
TimeSpan	timeout	Lock acquisition timeout.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
Task<PersistentState.WriteLockToken>	The token representing acquired write lock.

Exceptions

Type	Condition
TimeoutException	The lock has not been acquired in the specified time window.
OperationCanceledException	The operation has been canceled.

AppendAsync<TEntry>(TEntry, Int64)

Adds uncommitted log entry to the end of this log.

Declaration

public ValueTask AppendAsync<TEntry>(TEntry entry, long startIndex)

    where TEntry : IRaftLogEntry

Parameters

Type	Name	Description
TEntry	entry	The uncommitted log entry to be added into this audit trail.
Int64	startIndex	The index from which all previous log entries should be dropped and replaced with the new entry.

Returns

Type	Description
ValueTask	The task representing asynchronous state of the method.

Type Parameters

Name	Description
TEntry	The actual type of the supplied log entry.

Remarks

This is the only method that can be used for snapshot installation. The behavior of the method depends on the property. If log entry is a snapshot then the method erases all committed log entries prior to startIndex. If it is not, the method behaves in the same way as .

Exceptions

Type	Condition
InvalidOperationException	startIndex is less than the index of the last committed entry and entry is not a snapshot.

AppendAsync<TEntry>(TEntry, CancellationToken)

Adds uncommitted log entry to the end of this log.

Declaration

public ValueTask<long> AppendAsync<TEntry>(TEntry entry, CancellationToken token = default(CancellationToken))

    where TEntry : IRaftLogEntry

Parameters

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

Returns

Type	Description
ValueTask<Int64>	The index of the added entry.

Type Parameters

Name	Description
TEntry	The actual type of the supplied log entry.

Remarks

This method cannot be used to append a snapshot.

Exceptions

Type	Condition
InvalidOperationException	entry is the snapshot entry.

AppendAsync<TEntry>(PersistentState.WriteLockToken, TEntry, Int64)

Adds uncommitted log entry to the end of this log.

Declaration

public ValueTask AppendAsync<TEntry>(in PersistentState.WriteLockToken writeLock, TEntry entry, long startIndex)

    where TEntry : IRaftLogEntry

Parameters

Type	Name	Description
PersistentState.WriteLockToken	writeLock	The acquired lock token.
TEntry	entry	The uncommitted log entry to be added into this audit trail.
Int64	startIndex	The index from which all previous log entries should be dropped and replaced with the new entry.

Returns

Type	Description
ValueTask	The task representing asynchronous state of the method.

Type Parameters

Name	Description
TEntry	The actual type of the supplied log entry.

Exceptions

Type	Condition
ArgumentException	writeLock is invalid.
InvalidOperationException	startIndex is less than the index of the last committed entry and entry is not a snapshot.

AppendAsync<TEntry>(PersistentState.WriteLockToken, TEntry, CancellationToken)

Adds uncommitted log entry to the end of this log.

Declaration

public ValueTask<long> AppendAsync<TEntry>(in PersistentState.WriteLockToken writeLock, TEntry entry, CancellationToken token)

    where TEntry : IRaftLogEntry

Parameters

Type	Name	Description
PersistentState.WriteLockToken	writeLock	The acquired lock token.
TEntry	entry	The entry to add.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<Int64>	The index of the added entry.

Type Parameters

Name	Description
TEntry	The actual type of the supplied log entry.

Remarks

This method cannot be used to append a snapshot.

Exceptions

Type	Condition
ArgumentException	writeLock is invalid.
InvalidOperationException	entry is the snapshot entry.

AppendAsync<TEntry>(ILogEntryProducer<TEntry>, CancellationToken)

Adds uncommitted log entries to the end of this log.

Declaration

public ValueTask<long> AppendAsync<TEntry>(ILogEntryProducer<TEntry> entries, CancellationToken token = default(CancellationToken))

    where TEntry : IRaftLogEntry

Parameters

Type	Name	Description
ILogEntryProducer<TEntry>	entries	The entries to be added into this log.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<Int64>	Index of the first added entry.

Type Parameters

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

Remarks

This method should updates cached value provided by method called with argument of value false.

Exceptions

Type	Condition
ArgumentException	entries is empty.
InvalidOperationException	The collection of entries contains the snapshot entry.

ApplyAsync(PersistentState.LogEntry)

Applies the command represented by the log entry to the underlying database engine.

Declaration

protected virtual ValueTask ApplyAsync(PersistentState.LogEntry entry)

Parameters

Type	Name	Description
PersistentState.LogEntry	entry	The entry to be applied to the state machine.

Returns

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

Remarks

The base method does nothing so you don't need to call base implementation.

CommitAsync(Int64, CancellationToken)

Commits log entries into the underlying storage and marks these entries as committed.

Declaration

public ValueTask<long> CommitAsync(long endIndex, CancellationToken token)

Parameters

Type	Name	Description
Int64	endIndex	The index of the last entry to commit, inclusively; if null then commits all log entries started from the first uncommitted entry to the last existing log entry.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<Int64>	The actual number of committed entries.

Remarks

This method should updates cached value provided by method called with argument of value true. Additionally, it may force log compaction and squash all committed entries into single entry called snapshot.

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

CommitAsync(CancellationToken)

Commits log entries into the underlying storage and marks these entries as committed.

Declaration

public ValueTask<long> CommitAsync(CancellationToken token)

Parameters

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

Returns

Type	Description
ValueTask<Int64>	The actual number of committed entries.

Remarks

This method should updates cached value provided by method called with argument of value true. Additionally, it may force log compaction and squash all committed entries into single entry called snapshot.

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

CreateBackupAsync(Stream, CancellationToken)

Creates backup of this audit trail.

Declaration

public Task CreateBackupAsync(Stream output, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
Stream	output	The stream used to store backup.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
Task	A task representing state of asynchronous execution.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.

CreateSnapshotBuilder()

Creates a new snapshot builder.

Declaration

protected virtual PersistentState.SnapshotBuilder CreateSnapshotBuilder()

Returns

Type	Description
PersistentState.SnapshotBuilder	The snapshot builder; or null if snapshotting is not supported.

Dispose(Boolean)

Releases all resources associated with this audit trail.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
Boolean	disposing	true if called from Dispose(); false if called from finalizer.

Overrides

Disposable.Dispose(Boolean)

DisposeAsync()

Releases unmanaged resources asynchronously.

Declaration

public virtual ValueTask DisposeAsync()

Returns

Type	Description
ValueTask	A task representing state of asynchronous execution.

DropAsync(Int64, CancellationToken)

Dropes the uncommitted entries starting from the specified position to the end of the log.

Declaration

public ValueTask<long> DropAsync(long startIndex, CancellationToken token)

Parameters

Type	Name	Description
Int64	startIndex	The index of the first log entry to be dropped.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<Int64>	The actual number of dropped entries.

Exceptions

Type	Condition
InvalidOperationException	startIndex represents index of the committed entry.

EnsureConsistencyAsync(TimeSpan, CancellationToken)

Suspens the caller until the log entry with term equal to Term will be committed.

Declaration

public Task EnsureConsistencyAsync(TimeSpan timeout, CancellationToken token)

Parameters

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

Returns

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

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
TimeoutException	Timeout occurred.

FlushAsync()

Flushes the underlying data storage.

Declaration

protected virtual ValueTask FlushAsync()

Returns

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

GetLastIndex(Boolean)

Gets index of the committed or last log entry.

Declaration

public long GetLastIndex(bool committed)

Parameters

Type	Name	Description
Boolean	committed	true to get the index of highest log entry known to be committed; false to get the index of the last log entry.

Returns

Type	Description
Int64	The index of the log entry.

Remarks

This method is synchronous because returning value should be cached and updated in memory by implementing class.

InitializeAsync(CancellationToken)

Initializes this state asynchronously.

Declaration

public Task InitializeAsync(CancellationToken token = default(CancellationToken))

Parameters

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

Returns

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

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

IsValidToken(PersistentState.WriteLockToken)

Determines whether the specified lock token is valid.

Declaration

public bool IsValidToken(in PersistentState.WriteLockToken token)

Parameters

Type	Name	Description
PersistentState.WriteLockToken	token	The token of acquired lock to verify.

Returns

Type	Description
Boolean	true if token is valid; otherwise, false.

ReadAsync<TReader, TResult>(TReader, Int64, Int64, CancellationToken)

Gets log entries in the specified range.

Declaration

public ValueTask<TResult> ReadAsync<TReader, TResult>(TReader reader, long startIndex, long endIndex, CancellationToken token)

    where TReader : ILogEntryConsumer<IRaftLogEntry, TResult>

Parameters

Type	Name	Description
TReader	reader	The reader of the log entries.
Int64	startIndex	The index of the first requested log entry, inclusively.
Int64	endIndex	The index of the last requested log entry, inclusively.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<TResult>	The collection of log entries.

Type Parameters

Name	Description
TReader	The type of the reader.
TResult	The type of the result.

Remarks

This method may return less entries than endIndex - startIndex + 1. It may happen if the requested entries are committed entries and squashed into the single entry called snapshot. In this case the first entry in the collection is a snapshot entry. Additionally, the caller must call Dispose() to release resources associated with the audit trail segment with entries.

Exceptions

Type	Condition
ArgumentOutOfRangeException	startIndex or endIndex is negative.
IndexOutOfRangeException	endIndex is greater than the index of the last added entry.

ReadAsync<TReader, TResult>(TReader, Int64, CancellationToken)

Gets log entries starting from the specified index to the last log entry.

Declaration

public ValueTask<TResult> ReadAsync<TReader, TResult>(TReader reader, long startIndex, CancellationToken token)

    where TReader : ILogEntryConsumer<IRaftLogEntry, TResult>

Parameters

Type	Name	Description
TReader	reader	The reader of the log entries.
Int64	startIndex	The index of the first requested log entry, inclusively.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<TResult>	The collection of log entries.

Type Parameters

Name	Description
TReader	The type of the reader.
TResult	The type of the result.

Exceptions

Type	Condition
ArgumentOutOfRangeException	startIndex is negative.

ReplayAsync(CancellationToken)

Reconstructs dataset by calling ApplyAsync(PersistentState.LogEntry) for each committed entry.

Declaration

public Task ReplayAsync(CancellationToken token = default(CancellationToken))

Parameters

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

Returns

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

RestoreFromBackupAsync(Stream, DirectoryInfo, CancellationToken)

Restores persistent state from backup.

Declaration

public static Task RestoreFromBackupAsync(Stream backup, DirectoryInfo destination, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
Stream	backup	The stream containing backup.
DirectoryInfo	destination	The destination directory.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
Task	A task representing state of asynchronous execution.

Remarks

All files within destination directory will be deleted permanently.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.

WaitForCommitAsync(Int64, TimeSpan, CancellationToken)

Waits for specific commit.

Declaration

public Task<bool> WaitForCommitAsync(long index, TimeSpan timeout, CancellationToken token)

Parameters

Type	Name	Description
Int64	index	The index of the log record to be committed.
TimeSpan	timeout	The timeout used to wait for the commit.
CancellationToken	token	The token that can be used to cancel waiting.

Returns

Type	Description
Task<Boolean>	true if log entry is committed; otherwise, false.

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

WaitForCommitAsync(TimeSpan, CancellationToken)

Waits for the commit.

Declaration

public Task<bool> WaitForCommitAsync(TimeSpan timeout, CancellationToken token)

Parameters

Type	Name	Description
TimeSpan	timeout	The timeout used to wait for the commit.
CancellationToken	token	The token that can be used to cancel waiting.

Returns

Type	Description
Task<Boolean>	true if log entry is committed; otherwise, false.

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

Explicit Interface Implementations

IPersistentState.IncrementTermAsync()

Declaration

ValueTask<long> IPersistentState.IncrementTermAsync()

Returns

Type	Description
ValueTask<Int64>

IPersistentState.IsVotedFor(IRaftClusterMember)

Declaration

bool IPersistentState.IsVotedFor(IRaftClusterMember member)

Parameters

Type	Name	Description
IRaftClusterMember	member

Returns

Type	Description
Boolean

IPersistentState.UpdateTermAsync(Int64)

Declaration

ValueTask IPersistentState.UpdateTermAsync(long term)

Parameters

Type	Name	Description
Int64	term

Returns

Type	Description
ValueTask

IPersistentState.UpdateVotedForAsync(IRaftClusterMember)

Declaration

ValueTask IPersistentState.UpdateVotedForAsync(IRaftClusterMember member)

Parameters

Type	Name	Description
IRaftClusterMember	member

Returns

Type	Description
ValueTask

Implements

System.IDisposable

IPersistentState

IAuditTrail<TEntry>

System.IAsyncDisposable

Extension Methods

AsyncLockAcquisition.AcquireLockAsync<T>(T, TimeSpan)

AsyncLockAcquisition.AcquireLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireReadLockAsync<T>(T, TimeSpan)

AsyncLockAcquisition.AcquireReadLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, TimeSpan)

AsyncLockAcquisition.AcquireWriteLockAsync<T>(T, CancellationToken)

AsyncLockAcquisition.AcquireUpgradeableReadLockAsync<T>(T, TimeSpan)

AsyncLockAcquisition.AcquireUpgradeableReadLockAsync<T>(T, CancellationToken)

ObjectExtensions.GetUserData<T>(T)

ObjectExtensions.IsOneOf<T>(T, IEnumerable<T>)

ObjectExtensions.IsOneOf<T>(T, T[])

ObjectExtensions.Decompose<T, TResult1, TResult2>(T, Func<T, TResult1>, Func<T, TResult2>, out TResult1, out TResult2)

ObjectExtensions.Decompose<T, TResult1, TResult2>(T, ValueFunc<T, TResult1>, ValueFunc<T, TResult2>, out TResult1, out TResult2)

ObjectExtensions.Decompose<T, TResult1, TResult2>(T, Func<T, TResult1>, Func<T, TResult2>)

ObjectExtensions.Decompose<T, TResult1, TResult2>(T, ValueFunc<T, TResult1>, ValueFunc<T, TResult2>)

ObjectExtensions.As<T>(T)

LockAcquisition.AcquireReadLock<T>(T)

LockAcquisition.AcquireReadLock<T>(T, TimeSpan)

LockAcquisition.AcquireWriteLock<T>(T)

LockAcquisition.AcquireWriteLock<T>(T, TimeSpan)

LockAcquisition.AcquireUpgradeableReadLock<T>(T)

LockAcquisition.AcquireUpgradeableReadLock<T>(T, TimeSpan)

ExpressionBuilder.Const<T>(T)