PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, TSubmissionEntry> Methods

A general template for constructing log view adaptors that are based on a sequentially read and written primary. We use this to construct a variety of different log-consistency providers, all following the same basic pattern (read and write latest view from/to primary, and send notifications after writing).

Note that the log itself is transient, i.e. not actually saved to storage - only the latest view and some metadata (the log position, and write flags) is stored in the primary. It is safe to interleave calls to this adaptor (using grain scheduler only, of course).

Subclasses override ReadAsync and WriteAsync to read from / write to primary. Calls to the primary are serialized, i.e. never interleave.

ClearLogAsync(CancellationToken)

virtual

public virtual Task PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, ClearLogAsync(CancellationToken cancellationToken)

Clear the log stream completely. Throws System.NotSupportedException if the log stream does not support clearing.

Parameters

cancellationTokenCancellationToken: A cancellation token to cancel the operation.

Returns

A task that represents the asynchronous clear operation.

ClearPrimaryLogAsync(CancellationToken)

virtual

protected virtual Task PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, ClearPrimaryLogAsync(CancellationToken cancellationToken)

Clear the persisted log stream completely.

Parameters

cancellationTokenCancellationToken

ConfirmSubmittedEntries

public Task PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, ConfirmSubmittedEntries()

Confirm all submitted entries.

Waits until all previously submitted entries appear in the confirmed prefix of the log.

Returns

A task that completes after all entries are confirmed.

CopyTentativeState

protected TLogView PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, CopyTentativeState()

DisableStatsCollection

public void PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, DisableStatsCollection()

Disable stats collection

EnableStatsCollection

virtual

public virtual void PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, EnableStatsCollection()

method is virtual so subclasses can add their own events

EnsureClusterJoinedAsync

protected Task PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, EnsureClusterJoinedAsync()

Block until this cluster is joined to the multicluster.

GetConfirmedVersion

abstract

protected abstract int PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, GetConfirmedVersion()

Read version of cached global state.

GetCurrentBatchOfUpdates

protected TSubmissionEntry[] PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, GetCurrentBatchOfUpdates()

GetNumberPendingUpdates

protected int PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, GetNumberPendingUpdates()

GetStats

public LogConsistencyStatistics? PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, GetStats()

Get states

InitializeConfirmedView(TLogView)

abstract

protected abstract void PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, InitializeConfirmedView(TLogView initialstate)

Set confirmed view the initial value (a view of the empty log)

Parameters

initialstateTLogView

IsMyClusterJoined

protected bool PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, IsMyClusterJoined()

LastConfirmedView

abstract

protected abstract TLogView PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, LastConfirmedView()

Read cached global state.

MakeSubmissionEntry(TLogEntry)

abstract

protected abstract TSubmissionEntry PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, MakeSubmissionEntry(TLogEntry entry)

Create a submission entry for the submitted log entry. Using a type parameter so we can add protocol-specific info to this class.

Parameters

entryTLogEntry

Merge(INotificationMessage, INotificationMessage)

virtual

protected virtual INotificationMessage PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, Merge(INotificationMessage earliermessage, INotificationMessage latermessage)

Merge two notification messages, for batching. Override to handle notification subtypes.

Parameters

earliermessageINotificationMessage
latermessageINotificationMessage

NotifyPromises(int, bool)

protected void PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, NotifyPromises(int count, bool success)

send failure notifications

Parameters

countint
successbool

OnMessageReceived(ILogConsistencyProtocolMessage)

virtual

protected virtual Task<ILogConsistencyProtocolMessage> PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, OnMessageReceived(ILogConsistencyProtocolMessage payload)

Handle protocol messages.

Parameters

payloadILogConsistencyProtocolMessage

OnNotificationReceived(INotificationMessage)

virtual

protected virtual void PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, OnNotificationReceived(INotificationMessage payload)

Handle notification messages. Override this to handle notification subtypes.

Parameters

payloadINotificationMessage

OnProtocolMessageReceived(ILogConsistencyProtocolMessage)

public Task<ILogConsistencyProtocolMessage?> PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, OnProtocolMessageReceived(ILogConsistencyProtocolMessage payLoad)

Called from network

Parameters

payLoadILogConsistencyProtocolMessage

PostOnActivate

virtual

public virtual Task PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, PostOnActivate()

Called during activation, right after the user-defined Grain..

PostOnDeactivate

virtual

public virtual Task PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, PostOnDeactivate()

Called during deactivation, right after the user-defined Grain.

PreOnActivate

virtual

public virtual Task PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, PreOnActivate()

Called during activation, right before the user-defined Grain.

ProcessNotifications

virtual

protected virtual void PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, ProcessNotifications()

Process stored notifications during worker cycle. Override to handle notification subtypes.

ReadAsync

abstract

protected abstract Task PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, ReadAsync()

Read the latest primary state. Must block/retry until successful. Should not throw exceptions, but record them in Orleans.EventSourcing.Common.PrimaryBasedLogViewAdaptor.LastPrimaryIssue

RemoveStaleConditionalUpdates

protected void PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, RemoveStaleConditionalUpdates()

go through updates and remove all the conditional updates that have already failed

RetrieveLogSegment(int, int)

virtual

public virtual Task<IReadOnlyList<TLogEntry>> PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, RetrieveLogSegment(int fromVersion, int length)

Attempt to retrieve a segment of the log, possibly from storage. Throws System.NotSupportedException if the log cannot be read, which depends on the providers used and how they are configured.

Parameters

fromVersionint: the start position
lengthint: the end position

Returns

a

Submit(TLogEntry)

public void PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, Submit(TLogEntry logEntry)

Submit a single log entry to be appended to the global log, either at the current or at any later position.

Parameters

logEntryTLogEntry

SubmitRange(IEnumerable<TLogEntry>)

public void PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, SubmitRange(IEnumerable<TLogEntry> logEntries)

Submit a range of log entries to be appended atomically to the global log, either at the current or at any later position.

Parameters

logEntriesIEnumerable<TLogEntry>

Synchronize

public Task PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, Synchronize()

Get the latest log view and confirm all submitted entries.

Waits until all previously submitted entries appear in the confirmed prefix of the log, and forces a refresh of the confirmed prefix.

Returns

A task that completes after getting the latest version and confirming all entries.

TryAppend(TLogEntry)

public Task<bool> PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, TryAppend(TLogEntry logEntry)

Try to append a single log entry at the current position of the log.

Parameters

logEntryTLogEntry

Returns

true if the entry was appended successfully, or false if there was a concurrency conflict (i.e. some other entries were previously appended).

TryAppendRange(IEnumerable<TLogEntry>)

public Task<bool> PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, TryAppendRange(IEnumerable<TLogEntry> logEntries)

Try to append a range of log entries atomically at the current position of the log.

Parameters

logEntriesIEnumerable<TLogEntry>

Returns

true if the entries were appended successfully, or false if there was a concurrency conflict (i.e. some other entries were previously appended).

WriteAsync

abstract

protected abstract Task<int> PrimaryBasedLogViewAdaptor<TLogView, TLogEntry, WriteAsync()

Apply pending entries to the primary. Must block/retry until successful. Should not throw exceptions, but record them in Orleans.EventSourcing.Common.PrimaryBasedLogViewAdaptor.LastPrimaryIssue