Class PersistentState

Represents general purpose persistent audit trail compatible with Raft algorithm.

Inheritance

object

Disposable

PersistentState

DiskBasedStateMachine

MemoryBasedStateMachine

Implements

IDisposable

IPersistentState

IAuditTrail<IRaftLogEntry>

IAuditTrail

Inherited Members

Disposable.IsDisposed

Disposable.IsDisposing

Disposable.IsDisposingOrDisposed

Disposable.DisposedTask

Disposable.GetDisposedTask<T>()

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

Disposable.TrySetDisposedException(TaskCompletionSource)

Disposable.DisposeAsyncCore()

Disposable.DisposeAsync()

Disposable.TryBeginDispose()

Disposable.Dispose()

Disposable.Dispose(IEnumerable<IDisposable>)

Disposable.DisposeAsync(IEnumerable<IAsyncDisposable>)

Disposable.Dispose(ReadOnlySpan<IDisposable>)

Disposable.DisposeAsync(params 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 abstract class PersistentState : Disposable, IDisposable, IPersistentState, IAuditTrail<IRaftLogEntry>, IAuditTrail

Properties

| Edit this page View Source

LastCommittedEntryIndex

Gets the index of the last committed log entry.

Declaration

public long LastCommittedEntryIndex { get; }

Property Value

Type	Description
long

| Edit this page View Source

LastEntryIndex

Gets the index of the last added log entry.

Declaration

public long LastEntryIndex { get; }

Property Value

Type	Description
long

| Edit this page View Source

Location

Gets path to the folder with Write-Ahead Log files.

Declaration

protected DirectoryInfo Location { get; }

Property Value

Type	Description
DirectoryInfo

| Edit this page View Source

Term

Gets the current term.

Declaration

public long Term { get; }

Property Value

Type	Description
long

Methods

| Edit this page View Source

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) where TEntry : notnull, 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<long>	Index of the first added entry.

Type Parameters

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

Exceptions

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

| Edit this page View Source

AppendAsync<TEntry>(TEntry, bool, CancellationToken)

Adds uncommitted log entry to the end of this log.

Declaration

public ValueTask<long> AppendAsync<TEntry>(TEntry entry, bool addToCache, CancellationToken token = default) where TEntry : notnull, IRaftLogEntry

Parameters

Type	Name	Description
TEntry	entry	The entry to add.
bool	addToCache	true to copy the entry to in-memory cache to increase commit performance; false to avoid caching.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

Type	Description
ValueTask<long>	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.

| Edit this page View Source

AppendAsync<TEntry>(TEntry, long, CancellationToken)

Adds uncommitted log entry to the end of this log.

Declaration

public ValueTask AppendAsync<TEntry>(TEntry entry, long startIndex, CancellationToken token = default) where TEntry : notnull, IRaftLogEntry

Parameters

Type	Name	Description
TEntry	entry	The uncommitted log entry to be added into this audit trail.
long	startIndex	The index from which all previous log entries should be dropped and replaced with the new entry.
CancellationToken	token	The token that can be used to cancel the operation.

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 AppendAsync<TEntryImpl>(ILogEntryProducer<TEntryImpl>, long, bool, CancellationToken).

Exceptions

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

| Edit this page View Source

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) where TEntry : notnull, 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<long>	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.

| Edit this page View Source

ClearAsync(CancellationToken)

Removes all log entries from the log.

Declaration

protected virtual Task ClearAsync(CancellationToken token = default)

Parameters

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

Returns

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

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

| Edit this page View Source

CommitAsync(long, CancellationToken)

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

Declaration

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

Parameters

Type	Name	Description
long	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<long>	The actual number of committed entries.

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

| Edit this page View Source

CommitAsync(CancellationToken)

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

Declaration

public ValueTask<long> CommitAsync(CancellationToken token = default)

Parameters

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

Returns

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

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

| Edit this page View Source

CreateBackupAsync(Stream, CancellationToken)

Creates backup of this audit trail in TAR format.

Declaration

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

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.

| Edit this page View Source

CreateBinaryLogEntry(ReadOnlyMemory<byte>)

Creates a log entry with binary payload.

Declaration

public BinaryLogEntry CreateBinaryLogEntry(ReadOnlyMemory<byte> content)

Parameters

Type	Name	Description
ReadOnlyMemory<byte>	content	Binary payload.

Returns

Type	Description
BinaryLogEntry	The log entry encapsulating binary payload.

| Edit this page View Source

CreateBinaryLogEntry<T>(T)

Creates a log entry with binary payload.

Declaration

public BinaryLogEntry<T> CreateBinaryLogEntry<T>(T content) where T : notnull, IBinaryFormattable<T>

Parameters

Type	Name	Description
T	content	Binary payload.

Returns

Type	Description
BinaryLogEntry<T>	The log entry encapsulating binary payload.

Type Parameters

Name	Description
T	The type representing a payload convertible to binary format.

| Edit this page View Source

CreateJsonLogEntry<T>(T?)

Creates a log entry with JSON-serializable payload.

Declaration

public JsonLogEntry<T> CreateJsonLogEntry<T>(T? content) where T : notnull, IJsonSerializable<T>

Parameters

Type	Name	Description
T	content	JSON-serializable content of the log entry.

Returns

Type	Description
JsonLogEntry<T>	The log entry encapsulating JSON-serializable content.

Type Parameters

Name	Description
T	JSON-serializable type.

Dispose(bool)

Releases all resources associated with this audit trail.

Declaration

protected override void Dispose(bool disposing)

Parameters

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

Overrides

Disposable.Dispose(bool)

| Edit this page View Source

DropAsync(long, bool, CancellationToken)

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

Declaration

public ValueTask<long> DropAsync(long startIndex, bool reuseSpace = false, CancellationToken token = default)

Parameters

Type	Name	Description
long	startIndex	The index of the first log entry to be dropped.
bool	reuseSpace	true to drop entries quickly without cleaning of the disk space occupied by these entries; false to drop entries and reclaim the disk space occupied by these entries.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

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

Exceptions

Type	Condition
InvalidOperationException	`startIndex` represents index of the committed entry.

| Edit this page View Source

InitializeAsync(CancellationToken)

Initializes this state asynchronously.

Declaration

public virtual Task InitializeAsync(CancellationToken token = default)

Parameters

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

Returns

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

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

| Edit this page View Source

ReadAsync<TResult>(ILogEntryConsumer<IRaftLogEntry, TResult>, long, long, CancellationToken)

Gets log entries in the specified range.

Declaration

public ValueTask<TResult> ReadAsync<TResult>(ILogEntryConsumer<IRaftLogEntry, TResult> reader, long startIndex, long endIndex, CancellationToken token = default)

Parameters

Type	Name	Description
ILogEntryConsumer<IRaftLogEntry, TResult>	reader	The reader of the log entries.
long	startIndex	The index of the first requested log entry, inclusively.
long	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
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.

| Edit this page View Source

ReadAsync<TResult>(ILogEntryConsumer<IRaftLogEntry, TResult>, long, CancellationToken)

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

Declaration

public ValueTask<TResult> ReadAsync<TResult>(ILogEntryConsumer<IRaftLogEntry, TResult> reader, long startIndex, CancellationToken token = default)

Parameters

Type	Name	Description
ILogEntryConsumer<IRaftLogEntry, TResult>	reader	The reader of the log entries.
long	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
TResult	The type of the result.

Exceptions

Type	Condition
ArgumentOutOfRangeException	`startIndex` is negative.

| Edit this page View Source

RestoreFromBackupAsync(Stream, DirectoryInfo, CancellationToken)

Restores persistent state from backup represented in TAR format.

Declaration

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

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.

| Edit this page View Source

WaitForCommitAsync(long, CancellationToken)

Waits for the commit.

Declaration

public ValueTask WaitForCommitAsync(long index, CancellationToken token = default)

Parameters

Type	Name	Description
long	index	The index of the log record to be committed.
CancellationToken	token	The token that can be used to cancel waiting.

Returns

Type	Description
ValueTask	The task representing asynchronous result.

Exceptions

Type	Condition
ArgumentOutOfRangeException	`index` is less than 1.
OperationCanceledException	The operation has been cancelled.

| Edit this page View Source

WaitForCommitAsync(CancellationToken)

Waits for the commit.

Declaration

public ValueTask WaitForCommitAsync(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.

Exceptions

Type	Condition
OperationCanceledException	The operation has been cancelled.

Implements

IDisposable

IPersistentState

IAuditTrail<TEntry>

IAuditTrail

Extension Methods

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)