Edit

Share via


JournaledGrain<TGrainState,TEventBase> Class

Definition

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

public abstract class JournaledGrain<TGrainState,TEventBase> : Orleans.LogConsistency.LogConsistentGrainBase<TGrainState>, Orleans.LogConsistency.ILogConsistentGrain, Orleans.LogConsistency.ILogViewAdaptorHost<TGrainState,TEventBase>, Orleans.MultiCluster.ILogConsistencyProtocolParticipant where TGrainState : class, new() where TEventBase : class
public abstract class JournaledGrain<TGrainState,TEventBase> : Orleans.LogConsistency.LogConsistentGrain<TGrainState>, Orleans.IGrain, Orleans.LogConsistency.ILogViewAdaptorHost<TGrainState,TEventBase>, Orleans.MultiCluster.ILogConsistencyProtocolParticipant where TGrainState : class, new() where TEventBase : class
public abstract class JournaledGrain<TGrainState,TEventBase> : Orleans.EventSourcing.LogConsistentGrain<TGrainState>, Orleans.EventSourcing.ILogConsistencyProtocolParticipant, Orleans.EventSourcing.ILogViewAdaptorHost<TGrainState,TEventBase>, Orleans.IGrain where TGrainState : class, new() where TEventBase : class
type JournaledGrain<'GrainState, 'EventBase (requires 'GrainState : null and 'GrainState : (new : unit -> 'GrainState) and 'EventBase : null)> = class
    inherit LogConsistentGrainBase<'GrainState (requires 'GrainState : null and 'GrainState : (new : unit -> 'GrainState))>
    interface ILogConsistentGrain
    interface ILogConsistencyProtocolParticipant
    interface IGrain
    interface IAddressable
    interface ILogViewAdaptorHost<'GrainState, 'EventBase (requires 'GrainState : null and 'GrainState : (new : unit -> 'GrainState) and 'EventBase : null)>
    interface IConnectionIssueListener
type JournaledGrain<'GrainState, 'EventBase (requires 'GrainState : null and 'GrainState : (new : unit -> 'GrainState) and 'EventBase : null)> = class
    inherit LogConsistentGrain<'GrainState (requires 'GrainState : null and 'GrainState : (new : unit -> 'GrainState))>
    interface ILogConsistencyProtocolParticipant
    interface IGrain
    interface IAddressable
    interface ILogViewAdaptorHost<'GrainState, 'EventBase (requires 'GrainState : null and 'GrainState : (new : unit -> 'GrainState) and 'EventBase : null)>
    interface IConnectionIssueListener
Public MustInherit Class JournaledGrain(Of TGrainState, TEventBase)
Inherits LogConsistentGrainBase(Of TGrainState)
Implements ILogConsistencyProtocolParticipant, ILogConsistentGrain, ILogViewAdaptorHost(Of TGrainState, TEventBase)
Public MustInherit Class JournaledGrain(Of TGrainState, TEventBase)
Inherits LogConsistentGrain(Of TGrainState)
Implements IGrain, ILogConsistencyProtocolParticipant, ILogViewAdaptorHost(Of TGrainState, TEventBase)

Type Parameters

TGrainState

The type for the grain state, i.e. the aggregate view of the event log.

TEventBase

The common base class for the events

Inheritance
JournaledGrain<TGrainState,TEventBase>
Inheritance
LogConsistentGrain<TGrainState>
JournaledGrain<TGrainState,TEventBase>
Inheritance
LogConsistentGrain<TGrainState>
JournaledGrain<TGrainState,TEventBase>
Derived
Implements

Constructors

JournaledGrain<TGrainState,TEventBase>()

Initializes a new instance of the JournaledGrain<TGrainState,TEventBase> class.

JournaledGrain<TGrainState,TEventBase>(IGrainIdentity, IGrainRuntime)

This constructor is particularly useful for unit testing where test code can create a Grain and replace the IGrainIdentity, IGrainRuntime and State with test doubles (mocks/stubs).

Properties

DefaultAdaptorFactory

If there is no log-consistency provider specified, store versioned state using default storage provider

GrainContext (Inherited from Grain)
GrainFactory

Gets an object which can be used to access other grains. Null if this grain is not associated with a Runtime, such as when created directly for unit testing.

(Inherited from Grain)
GrainReference (Inherited from Grain)
IdentityString

String representation of grain's SiloIdentity including type and primary key.

(Inherited from Grain)
RuntimeIdentity

A unique identifier for the current silo. There is no semantic content to this string, but it may be useful for logging.

(Inherited from Grain)
ServiceProvider

Gets the IServiceProvider managed by the runtime. Null if this grain is not associated with a Runtime, such as when created directly for unit testing.

(Inherited from Grain)
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.

UnresolvedConnectionIssues

Gets a list of all currently unresolved connection issues.

Version

Gets the version of the current confirmed state. Equals the total number of confirmed events.

Methods

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

DeactivateOnIdle()

Deactivate this activation of the grain after the current grain method call is completed. This call will mark this activation of the current grain to be deactivated and removed at the end of the current method. The next call to this grain will result in a different activation to be used, which typical means a new activation will be created automatically by the runtime.

(Inherited from Grain)
DelayDeactivation(TimeSpan)

Delay Deactivation of this activation at least for the specified time duration. A positive timeSpan value means “prevent GC of this activation for that time span”. A negative timeSpan value means “cancel the previous setting of the DelayDeactivation call and make this activation behave based on the regular Activation Garbage Collection settings”. DeactivateOnIdle method would undo / override any current “keep alive” setting, making this grain immediately available for deactivation.

(Inherited from Grain)
DisableStatsCollection() System.Object.DisableStatsCollection
EnableStatsCollection() System.Object.EnableStatsCollection
GetLogger()

Returns a logger object that this grain's code can use for tracing. The name of the logger will be derived from the grain class name.

(Inherited from Grain)
GetLogger(String)

Returns a logger object that this grain's code can use for tracing.

(Inherited from Grain)
GetReminder(String)

Returns a previously registered reminder.

(Inherited from Grain)
GetReminders()

Returns a list of all reminders registered by the grain.

(Inherited from Grain)
GetStats() System.Object.GetStats
GetStreamProvider(String) (Inherited from Grain)
GetStreamProviders() (Inherited from Grain)
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

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

MigrateOnIdle()

Starts an attempt to migrating this instance to another location. Migration captures the current RequestContext, making it available to the activation's placement director so that it can consider it when selecting a new location. Migration will occur asynchronously, when no requests are executing, and will not occur if the activation's placement director does not select an alternative location.

(Inherited from Grain)
OnActivateAsync()

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.

OnActivateAsync()

This method is called at the end of the process of activating a grain. It is called before any messages have been dispatched to the grain. For grains with declared persistent state, this method is called after the State property has been populated.

(Inherited from 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.

OnActivateAsync(CancellationToken)

This method is called at the end of the process of activating a grain. It is called before any messages have been dispatched to the grain. For grains with declared persistent state, this method is called after the State property has been populated.

(Inherited from Grain)
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.

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

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

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.

OnDeactivateAsync()

This method is called at the begining of the process of deactivating a grain.

(Inherited from Grain)
OnDeactivateAsync(DeactivationReason, CancellationToken)

This method is called at the beginning of the process of deactivating a grain.

(Inherited from Grain)
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.

Participate(IGrainLifecycle) (Inherited from Grain)
Participate(IGrainLifecycle) (Inherited from LogConsistentGrain<TView>)
Participate(IGrainLifecycle) (Inherited from LogConsistentGrain<TView>)
RaiseConditionalEvent<TEvent>(TEvent)

Raise an event conditionally. Succeeds only if there are no conflicts, that is, no other events were raised in the meantime.

RaiseConditionalEvents<TEvent>(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>(TEvent)

Raises an event.

RaiseEvents<TEvent>(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

RegisterOrUpdateReminder(String, TimeSpan, TimeSpan)

Registers a persistent, reliable reminder to send regular notifications (reminders) to the grain. The grain must implement the Orleans.IRemindable interface, and reminders for this grain will be sent to the ReceiveReminder callback method. If the current grain is deactivated when the timer fires, a new activation of this grain will be created to receive this reminder. If an existing reminder with the same name already exists, that reminder will be overwritten with this new reminder. Reminders will always be received by one activation of this grain, even if multiple activations exist for this grain.

(Inherited from Grain)
RegisterTimer(Func<Object,Task>, Object, TimeSpan, TimeSpan)
Obsolete.

Registers a timer to send periodic callbacks to this grain.

(Inherited from Grain)
RetrieveConfirmedEvents(Int32, Int32)

Retrieves a segment of the confirmed event sequence, possibly from storage. Throws 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.

UnregisterReminder(IGrainReminder)

Unregisters a previously registered reminder.

(Inherited from Grain)

Explicit Interface Implementations

IConnectionIssueListener.OnConnectionIssue(ConnectionIssue)

called by adaptor on connection issues.

IConnectionIssueListener.OnConnectionIssue(ConnectionIssue)

called by adaptor on connection issues.

IConnectionIssueListener.OnConnectionIssueResolved(ConnectionIssue)

Called by adaptor when a connection issue is resolved.

IConnectionIssueListener.OnConnectionIssueResolved(ConnectionIssue)

called by adaptor when a connection issue is resolved.

IGrainBase.GrainContext (Inherited from Grain)
ILogConsistencyProtocolParticipant.DeactivateProtocolParticipant()

Notify log view adaptor of deactivation

ILogConsistencyProtocolParticipant.DeactivateProtocolParticipant()

Notify log view adaptor of deactivation

ILogConsistencyProtocolParticipant.OnMultiClusterConfigurationChange(MultiClusterConfiguration)

Receive a configuration change, pass on to log view adaptor.

ILogConsistencyProtocolParticipant.OnProtocolMessageReceived(ILogConsistencyProtocolMessage)

Receive a protocol message from other clusters, passed on to log view adaptor.

ILogConsistencyProtocolParticipant.PostActivateProtocolParticipant()

Notify log view adaptor of activation (called after user-level OnActivate)

ILogConsistencyProtocolParticipant.PostActivateProtocolParticipant()

Notify log view adaptor of activation (called after user-level OnActivate)

ILogConsistencyProtocolParticipant.PreActivateProtocolParticipant()

Notify log view adaptor of activation (called before user-level OnActivate)

ILogConsistencyProtocolParticipant.PreActivateProtocolParticipant()

Notify log view adaptor of activation (called before user-level OnActivate)

ILogConsistentGrain.DefaultAdaptorFactory

If there is no log-consistency provider specified, store versioned state using default storage provider

ILogConsistentGrain.InstallAdaptor(ILogViewAdaptorFactory, Object, String, IStorageProvider, 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

ILogViewAdaptorHost<TGrainState,TEventBase>.OnViewChanged(Boolean, Boolean)

Called by adaptor on state change.

ILogViewAdaptorHost<TGrainState,TEventBase>.OnViewChanged(Boolean, Boolean)

called by adaptor on state change.

ILogViewAdaptorHost<TGrainState,TEventBase>.UpdateView(TGrainState, TEventBase)

Called by adaptor to update the view when entries are appended.

ILogViewAdaptorHost<TGrainState,TEventBase>.UpdateView(TGrainState, TEventBase)

called by adaptor to update the view when entries are appended.

Extension Methods

DeactivateOnIdle(IGrainBase)

Deactivate this grain activation after the current grain method call is completed. This call will mark this activation of the current grain to be deactivated and removed at the end of the current method. The next call to this grain will result in a different activation to be used, which typical means a new activation will be created automatically by the runtime.

MigrateOnIdle(IGrainBase)

Starts an attempt to migrating this instance to another location. Migration captures the current RequestContext, making it available to the activation's placement director so that it can consider it when selecting a new location. Migration will occur asynchronously, when no requests are executing, and will not occur if the activation's placement director does not select an alternative location.

RegisterGrainTimer(IGrainBase, Func<CancellationToken,Task>, GrainTimerCreationOptions)

Creates a grain timer.

RegisterGrainTimer(IGrainBase, Func<CancellationToken,Task>, TimeSpan, TimeSpan)

Creates a grain timer.

RegisterGrainTimer(IGrainBase, Func<Task>, GrainTimerCreationOptions)
RegisterGrainTimer(IGrainBase, Func<Task>, TimeSpan, TimeSpan)

Creates a grain timer.

RegisterGrainTimer<TState>(IGrainBase, Func<TState,CancellationToken,Task>, TState, GrainTimerCreationOptions)

Creates a grain timer.

RegisterGrainTimer<TState>(IGrainBase, Func<TState,CancellationToken,Task>, TState, TimeSpan, TimeSpan)

Creates a grain timer.

RegisterGrainTimer<TState>(IGrainBase, Func<TState,Task>, TState, GrainTimerCreationOptions)
RegisterGrainTimer<TState>(IGrainBase, Func<TState,Task>, TState, TimeSpan, TimeSpan)

Creates a grain timer.

AsReference(IAddressable, Type)

Returns a typed reference to the provided grain.

AsReference<TGrainInterface>(IAddressable)

Returns a typed reference to the provided grain.

BindGrainReference(IAddressable, IGrainFactory)

Binds the grain reference to the provided IGrainFactory.

Cast(IAddressable, Type)

Returns a typed reference to the provided grain.

Cast<TGrainInterface>(IAddressable)

Returns a typed reference to the provided grain.

GetGrainId(IAddressable)

Returns the grain id corresponding to the provided grain.

GetGrainIdentity(IGrain)
GetPrimaryKey(IGrain)
GetPrimaryKey(IGrain, String)
GetPrimaryKey(IAddressable)

Returns the Guid representation of a grain primary key.

GetPrimaryKey(IAddressable, String)

Returns the Guid representation of a grain primary key.

GetPrimaryKeyLong(IGrain)
GetPrimaryKeyLong(IGrain, String)
GetPrimaryKeyLong(IAddressable)

Returns the long representation of a grain primary key.

GetPrimaryKeyLong(IAddressable, String)

Returns the long representation of a grain primary key.

GetPrimaryKeyString(IAddressable)

Returns the string primary key of the grain.

IsPrimaryKeyBasedOnLong(IAddressable)

Returns whether part of the primary key is of type long.

GetReminder(Grain, String)

Returns a previously registered reminder.

GetReminder(IGrainBase, String)

Returns a previously registered reminder.

GetReminders(Grain)

Returns a list of all reminders registered by the grain.

GetReminders(IGrainBase)

Returns a list of all reminders registered by the grain.

RegisterOrUpdateReminder(Grain, String, TimeSpan, TimeSpan)

Registers a persistent, reliable reminder to send regular notifications (reminders) to the grain. The grain must implement the Orleans.IRemindable interface, and reminders for this grain will be sent to the ReceiveReminder callback method. If the current grain is deactivated when the timer fires, a new activation of this grain will be created to receive this reminder. If an existing reminder with the same name already exists, that reminder will be overwritten with this new reminder. Reminders will always be received by one activation of this grain, even if multiple activations exist for this grain.

RegisterOrUpdateReminder(IGrainBase, String, TimeSpan, TimeSpan)

Registers a persistent, reliable reminder to send regular notifications (reminders) to the grain. The grain must implement the Orleans.IRemindable interface, and reminders for this grain will be sent to the ReceiveReminder callback method. If the current grain is deactivated when the timer fires, a new activation of this grain will be created to receive this reminder. If an existing reminder with the same name already exists, that reminder will be overwritten with this new reminder. Reminders will always be received by one activation of this grain, even if multiple activations exist for this grain.

UnregisterReminder(Grain, IGrainReminder)

Unregisters a previously registered reminder.

UnregisterReminder(IGrainBase, IGrainReminder)

Unregisters a previously registered reminder.

GetStreamProvider(Grain, String)

Gets the stream provider with the specified name.

GetStreamProvider(IGrainBase, String)

Gets the stream provider with the specified name.

GetLogger(Grain)

Returns a logger object that this grain's code can use for tracing. The name of the logger will be derived from the grain class name.

GetLogger(Grain, String)

Returns a logger object that this grain's code can use for tracing.

GetGrainStorage(Grain, IServiceProvider)

Acquire the storage provider associated with the grain type.

Applies to