Skip to content
Orleans logoMicrosoft Orleans

JournaledGrain<TGrainState, TEventBase>

class

Namespace: Orleans.EventSourcing

A base class for log-consistent grains using standard event-sourcing terminology. All operations are reentrancy-safe. 
public abstract class JournaledGrain<TGrainState, TEventBase> : LogConsistentGrain<TGrainState>, IConnectionIssueListener, ILogConsistencyProtocolParticipant, ILogViewAdaptorHost<TGrainState, TEventBase>, IGrain, IAddressable
    where TGrainState : class, new()
    where TEventBase : class

Constructors

Properties

  • DefaultAdaptorFactory If there is no log-consistency provider specified, store versioned state using default storage provider
  • State Gets the current confirmed state. Includes only confirmed events.
  • TentativeState Gets the current tentative state. Includes both confirmed and unconfirmed events.
  • UnconfirmedEvents Returns the current queue of unconfirmed events.
  • Version Gets the version of the current confirmed state. Equals the total number of confirmed events.

Methods

  • ClearLogAsync(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.
  • 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

  • DisableStatsCollection
  • EnableStatsCollection
  • GetStats
  • InstallAdaptor(ILogViewAdaptorFactory, object, string, IGrainStorage?, ILogConsistencyProtocolServices) 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
  • OnActivateAsync(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.
  • OnConnectionIssue(ConnectionIssue) 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.

  • OnConnectionIssueResolved(ConnectionIssue) 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.

  • 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 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) Raise an event conditionally. Succeeds only if there are no conflicts, that is, no other events were raised in the meantime.
  • RaiseConditionalEvents(IEnumerable<TEvent>) 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.
  • RaiseEvent(TEvent) Raises an event.
  • RaiseEvents(IEnumerable<TEvent>) Raise multiple events, as an atomic sequence.
  • 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

  • RetrieveConfirmedEvents(int, int) 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.
  • TransitionState(TGrainState, TEventBase) 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.