Skip to content
Orleans logoMicrosoft Orleans

JournaledGrain<TGrainState, TEventBase> Methods

A base class for log-consistent grains using standard event-sourcing terminology. All operations are reentrancy-safe.

ClearLogAsync(CancellationToken)

View source
protected Task JournaledGrain<TGrainState, ClearLogAsync(CancellationToken cancellationToken = default(CancellationToken))
Clears the log of all confirmed events. Reset the state to the initial state, and discards all unconfirmed events. Throws System.NotSupportedException if the log cannot be cleared.

Parameters

cancellationTokenCancellationToken

ConfirmEvents

View source
protected Task JournaledGrain<TGrainState, ConfirmEvents()
Waits until all previously raised events have been confirmed.

await this after raising one or more events, to ensure events are persisted before proceeding, or to guarantee strong consistency (linearizability) even if there are multiple instances of this grain

Returns

a task that completes once the events have been confirmed.

InstallAdaptor(ILogViewAdaptorFactory, object, string, IGrainStorage?, ILogConsistencyProtocolServices)

override
View source
protected override void JournaledGrain<TGrainState, InstallAdaptor(ILogViewAdaptorFactory factory, object initialState, string graintypename, IGrainStorage? grainStorage, ILogConsistencyProtocolServices services)
Called right after grain is constructed, to install the adaptor. The log-consistency provider contains a factory method that constructs the adaptor with chosen types for this grain

Parameters

factoryILogViewAdaptorFactory
initialStateobject
graintypenamestring
grainStorageIGrainStorage?
servicesILogConsistencyProtocolServices

OnActivateAsync(CancellationToken)

override
View source
public override Task JournaledGrain<TGrainState, OnActivateAsync(CancellationToken cancellationToken)
By default, upon activation, the journaled grain waits until it has loaded the latest view from storage. Subclasses can override this behavior, and skip the wait if desired.

Parameters

cancellationTokenCancellationToken

OnConnectionIssue(ConnectionIssue)

virtual
View source
protected virtual void JournaledGrain<TGrainState, OnConnectionIssue(ConnectionIssue issue)
Called when the underlying persistence or replication protocol is running into some sort of connection trouble.

Override this to monitor the health of the log-consistency protocol and/or to customize retry delays. Any exceptions thrown are caught and logged by the ILogViewAdaptorFactory.

Parameters

issueConnectionIssue

Returns

The time to wait before retrying

OnConnectionIssueResolved(ConnectionIssue)

virtual
View source
protected virtual void JournaledGrain<TGrainState, OnConnectionIssueResolved(ConnectionIssue issue)
Called when a previously reported connection issue has been resolved.

Override this to monitor the health of the log-consistency protocol. Any exceptions thrown are caught and logged by the ILogViewAdaptorFactory.

Parameters

issueConnectionIssue

OnStateChanged

virtual
View source
protected virtual void JournaledGrain<TGrainState, OnStateChanged()
Called after the confirmed state may have changed (i.e. the confirmed version number is larger).

Override this to react to changes of the confirmed state.

OnTentativeStateChanged

virtual
View source
protected virtual void JournaledGrain<TGrainState, OnTentativeStateChanged()
Called whenever the tentative state may have changed due to local or remote events.

Override this to react to changes of the state.

RaiseConditionalEvent(TEvent)

virtual
View source
protected virtual Task<bool> JournaledGrain<TGrainState, RaiseConditionalEvent<TEvent>(TEvent @event)
Raise an event conditionally. Succeeds only if there are no conflicts, that is, no other events were raised in the meantime.

Parameters

eventTEvent
Event to raise.

Returns

true if successful, false if there was a conflict.

RaiseConditionalEvents(IEnumerable<TEvent>)

virtual
View source
protected virtual Task<bool> JournaledGrain<TGrainState, RaiseConditionalEvents<TEvent>(IEnumerable<TEvent> events)
Raise multiple events, as an atomic sequence, conditionally. Succeeds only if there are no conflicts, that is, no other events were raised in the meantime.

Parameters

eventsIEnumerable<TEvent>
Events to raise

Returns

true if successful, false if there was a conflict.

RaiseEvent(TEvent)

virtual
View source
protected virtual void JournaledGrain<TGrainState, RaiseEvent<TEvent>(TEvent @event)
Raises an event.

Parameters

eventTEvent
Event to raise.

RaiseEvents(IEnumerable<TEvent>)

virtual
View source
protected virtual void JournaledGrain<TGrainState, RaiseEvents<TEvent>(IEnumerable<TEvent> events)
Raise multiple events, as an atomic sequence.

Parameters

eventsIEnumerable<TEvent>
Events to raise.

RefreshNow

View source
protected Task JournaledGrain<TGrainState, RefreshNow()
Retrieves the latest state now, and confirms all previously raised events. Effectively, this enforces synchronization with the global state.

Await this before reading the state to ensure strong consistency (linearizability) even if there are multiple instances of this grain

Returns

a task that completes once the log has been refreshed and the events have been confirmed.

RetrieveConfirmedEvents(int, int)

View source
protected Task<IReadOnlyList<TEventBase>> JournaledGrain<TGrainState, RetrieveConfirmedEvents(int fromVersion, int toVersion)
Retrieves a segment of the confirmed event sequence, possibly from storage. Throws System.NotSupportedException if the events are not available to read. Whether events are available, and for how long, depends on the providers used and how they are configured.

Parameters

fromVersionint
the position of the event sequence from which to start
toVersionint
the position of the event sequence on which to end

Returns

a task which returns the sequence of events between the two versions

TransitionState(TGrainState, TEventBase)

virtual
View source
protected virtual void JournaledGrain<TGrainState, TransitionState(TGrainState state, TEventBase @event)
Defines how to apply events to the state. Unless it is overridden in the subclass, it calls a dynamic "Apply" function on the state, with the event as a parameter. All exceptions thrown by this method are caught and logged by the log view provider.

Override this to customize how to transition the state for a given event.

Parameters

stateTGrainState
The state.
eventTEventBase
The event.