Show / Hide Table of Contents

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.CreateException()
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<T>(ReadOnlySpan<T>)
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 : 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 : 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 : 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 : 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 canceled.

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

See Also
TransformAsync<TInput>(TInput, CancellationToken)
| Edit this page View Source

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

WaitForApplyAsync(long, CancellationToken)

Waits for the commit.

Declaration
public ValueTask WaitForApplyAsync(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 canceled.

| Edit this page View Source

WaitForApplyAsync(CancellationToken)

Waits for the commit.

Declaration
public ValueTask WaitForApplyAsync(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

Command.AppendAsync<TCommand>(IPersistentState, TCommand, object?, CancellationToken)
PersistentStateExtensions.AppendAsync(IPersistentState, ReadOnlyMemory<byte>, object?, CancellationToken)
PersistentStateExtensions.AppendAsync<T>(IPersistentState, T, object?, CancellationToken)
PersistentStateExtensions.AppendJsonAsync<T>(IPersistentState, 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)

See Also

MemoryBasedStateMachine
DiskBasedStateMachine
  • Edit this page
  • View Source
☀
☾
In this article
Back to top
Supported by the .NET Foundation
☀
☾