Class PersistentState

Represents general purpose persistent audit trail compatible with Raft algorithm.

Inheritance

Object

PersistentState

Implements

IPersistentState

IAuditTrail<IRaftLogEntry>

IAuditTrail

Namespace: DotNext.Net.Cluster.Consensus.Raft

Assembly: DotNext.Net.Cluster.dll

Syntax

public class PersistentState : Disposable, IPersistentState, IAuditTrail<IRaftLogEntry>, IAuditTrail

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.

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.

Properties

Buffer

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

Declaration

protected byte[] Buffer { get; }

Property Value

Type	Description
Byte[]

Remarks

The buffer cannot be used concurrently. Access to it should be synchronized using SyncRoot property.

SyncRoot

Gets the lock that can be used to synchronize access to this object.

Declaration

protected AsyncLock SyncRoot { get; }

Property Value

Type	Description
AsyncLock

Methods

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 IsSnapshot 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 DotNext.Net.Cluster.Consensus.Raft.PersistentState.AppendAsync``1(DotNext.Net.Cluster.Replication.ILogEntryProducer{``0},System.Int64,System.Boolean,CancellationToken).

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 = null)

    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 GetLastIndex(Boolean) called with argument of value false.

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(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 GetLastIndex(Boolean) called with argument of value true. Additionally, it may force log compaction and squash all committed entries into single entry called snapshot.

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 GetLastIndex(Boolean) called with argument of value true. Additionally, it may force log compaction and squash all committed entries into single entry called snapshot.

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 ; false if called from finalizer.

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.

EnsureConsistencyAsync(CancellationToken)

Ensures that all committed entries are applied to the underlying data state machine known as database engine.

Declaration

public Task EnsureConsistencyAsync(CancellationToken token = null)

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.

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.

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.

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 to release resources associated with the audit trail segment with entries.

ReplayAsync(CancellationToken)

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

Declaration

public Task ReplayAsync(CancellationToken token = null)

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.

WaitForCommitAsync(Int64, TimeSpan, CancellationToken)

Waits for the commit.

Declaration

public Task 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	The task representing waiting operation.

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.Term

Declaration

long IPersistentState.Term { get; }

Returns

Type	Description
Int64

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

IAuditTrail<IRaftLogEntry>.AppendAsync<TEntryImpl>(ILogEntryProducer<TEntryImpl>, Int64, Boolean, CancellationToken)

Declaration

ValueTask IAuditTrail<IRaftLogEntry>.AppendAsync<TEntry>(ILogEntryProducer<TEntry> entries, long startIndex, bool skipCommitted, CancellationToken token)

    where TEntry : IRaftLogEntry

Parameters

Type	Name	Description
ILogEntryProducer<TEntry>	entries
Int64	startIndex
Boolean	skipCommitted
CancellationToken	token

Returns

Type	Description
ValueTask

Type Parameters

Name	Description
TEntry

IAuditTrail<IRaftLogEntry>.First

Declaration

IRaftLogEntry IAuditTrail<IRaftLogEntry>.First { get; }

Returns

Type	Description
IRaftLogEntry

Implements

IPersistentState

IAuditTrail<TEntry>

IAuditTrail

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)

ExpressionBuilder.Const<T>(T)

ObjectExtensions.GetUserData<T>(T)

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

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

ObjectExtensions.Decompose<T, R1, R2>(T, Func<T, R1>, Func<T, R2>, out R1, out R2)

ObjectExtensions.Decompose<T, R1, R2>(T, ValueFunc<T, R1>, ValueFunc<T, R2>, out R1, out R2)

ObjectExtensions.Decompose<T, R1, R2>(T, Func<T, R1>, Func<T, R2>)

ObjectExtensions.Decompose<T, R1, R2>(T, ValueFunc<T, R1>, ValueFunc<T, R2>)

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)