Class WriteAheadLog

Represents the general-purpose Raft WAL.

Inheritance

object

Disposable

WriteAheadLog

Implements

IDisposable

IAsyncDisposable

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

Assembly: DotNext.Net.Cluster.dll

Syntax

public class WriteAheadLog : Disposable, IDisposable, IAsyncDisposable, IPersistentState, IAuditTrail<IRaftLogEntry>, IAuditTrail

Constructors

WriteAheadLog(Options, IStateMachine)

Initializes a new WAL.

Declaration

public WriteAheadLog(WriteAheadLog.Options configuration, IStateMachine stateMachine)

Parameters

Type	Name	Description
WriteAheadLog.Options	configuration	The configuration of the write-ahead log.
IStateMachine	stateMachine	The state machine.

Properties

LastAppliedIndex

Gets the index of the last log entry applied to the underlying state machine.

Declaration

public long LastAppliedIndex { get; }

Property Value

Type	Description
long

LastCommittedEntryIndex

Gets the index of the last committed log entry.

Declaration

public long LastCommittedEntryIndex { get; }

Property Value

Type	Description
long

LastEntryIndex

Gets the index of the last added log entry (committed or not).

Declaration

public long LastEntryIndex { get; }

Property Value

Type	Description
long

Methods

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

Adds uncommitted log entries into this log.

Declaration

public ValueTask AppendAsync<TEntry>(ILogEntryProducer<TEntry> entries, long startIndex, bool skipCommitted = false, CancellationToken token = default) where TEntry : IRaftLogEntry

Parameters

Type	Name	Description
ILogEntryProducer<TEntry>	entries	Stateful object that is responsible for supplying log entries.
long	startIndex	The index from which all previous log entries should be dropped and replaced with new entries.
bool	skipCommitted	true to skip committed entries from entries instead of throwing exception.
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

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.
InvalidOperationException	startIndex is less than the index of the last committed entry and skipCommitted is false; or the collection of entries contains the snapshot entry.

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

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.
OperationCanceledException	The operation has been canceled.

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

Remarks

This method cannot be used to append a snapshot.

Exceptions

Type	Condition
InvalidOperationException	entry is the snapshot entry.
OperationCanceledException	The operation has been canceled.

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.
CancellationToken	token	The token that can be used to cancel the operation.

Returns

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

Remarks

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

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.

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)

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.

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.

FlushAsync(CancellationToken)

Flushes and writes the checkpoint.

Declaration

public Task FlushAsync(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 state of the operation.

Exceptions

Type	Condition
OperationCanceledException	The operation has been canceled.

InitializeAsync(CancellationToken)

Initializes the log 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

Remarks

The default implementation applies committed log entries to the underlying state machine.

ReadAsync(long, long, CancellationToken)

Reads the log entries.

Declaration

public ValueTask<WriteAheadLog.LogEntryReader> ReadAsync(long startIndex, long endIndex, CancellationToken token = default)

Parameters

Type	Name	Description
long	startIndex	The index of the first requested log entry.
long	endIndex	The index of the last requested log entry.
CancellationToken	token	The token that can be used to cancel the enumeration.

Returns

Type	Description
ValueTask<WriteAheadLog.LogEntryReader>	Lazy collection of log entries.

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 fewer entries than endIndex - startIndex + 1. It may happen if the requested entries are committed 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.
OperationCanceledException	The operation has been canceled.

See Also

IsSnapshot

WaitForApplyAsync(long, CancellationToken)

Waits for the entry to be applied to the underlying state machine.

Declaration

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

Parameters

Type	Name	Description
long	index	The index of the log record to be applied.
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.

WaitForApplyAsync(CancellationToken)

Waits for the entry to be applied to the underlying state machine.

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

Implements

IDisposable

IAsyncDisposable

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)