Class Grain

The abstract base class for all grain classes.

Inheritance

System.Object

Grain

Grain<TGrainState>

Implements

IAddressable

ILifecycleParticipant<IGrainLifecycle>

Namespace: Orleans

Assembly: Orleans.Core.Abstractions.dll

Syntax

public abstract class Grain : object, IAddressable, ILifecycleParticipant<IGrainLifecycle>

Constructors

Grain()

This constructor should never be invoked. We expose it so that client code (subclasses of Grain) do not have to add a constructor. Client code should use the GrainFactory property to get a reference to a Grain.

Declaration

protected Grain()

Grain(IGrainIdentity, IGrainRuntime)

Grain implementers do NOT have to expose this constructor but can choose to do so. This constructor is particularly useful for unit testing where test code can create a Grain and replace the IGrainIdentity and IGrainRuntime with test doubles (mocks/stubs).

Declaration

protected Grain(IGrainIdentity identity, IGrainRuntime runtime)

Parameters

Type	Name	Description
IGrainIdentity	identity
IGrainRuntime	runtime

Properties

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.

Declaration

protected IGrainFactory GrainFactory { get; }

Property Value

Type	Description
IGrainFactory

GrainReference

Declaration

public GrainReference GrainReference { get; }

Property Value

Type	Description
GrainReference

IdentityString

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

Declaration

public string IdentityString { get; }

Property Value

Type	Description
System.String

RuntimeIdentity

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

Declaration

public string RuntimeIdentity { get; }

Property Value

Type	Description
System.String

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.

Declaration

protected IServiceProvider ServiceProvider { get; }

Property Value

Type	Description
IServiceProvider

Methods

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.

Declaration

protected void DeactivateOnIdle()

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.

Declaration

protected void DelayDeactivation(TimeSpan timeSpan)

Parameters

Type	Name	Description
TimeSpan	timeSpan

GetReminder(String)

Returns a previously registered reminder.

Declaration

protected Task<IGrainReminder> GetReminder(string reminderName)

Parameters

Type	Name	Description
System.String	reminderName	Reminder to return

Returns

Type	Description
Task<IGrainReminder>	Promise for Reminder handle.

GetReminders()

Returns a list of all reminders registered by the grain.

Declaration

protected Task<List<IGrainReminder>> GetReminders()

Returns

Type	Description
Task<List<IGrainReminder>>	Promise for list of Reminders registered for this grain.

GetStreamProvider(String)

Declaration

protected IStreamProvider GetStreamProvider(string name)

Parameters

Type	Name	Description
System.String	name

Returns

Type	Description
IStreamProvider

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.

Declaration

public virtual Task OnActivateAsync()

Returns

Type	Description
Task

OnDeactivateAsync()

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

Declaration

public virtual Task OnDeactivateAsync()

Returns

Type	Description
Task

Participate(IGrainLifecycle)

Declaration

public virtual void Participate(IGrainLifecycle lifecycle)

Parameters

Type	Name	Description
IGrainLifecycle	lifecycle

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.

Declaration

protected Task<IGrainReminder> RegisterOrUpdateReminder(string reminderName, TimeSpan dueTime, TimeSpan period)

Parameters

Type	Name	Description
System.String	reminderName	Name of this reminder
TimeSpan	dueTime	Due time for this reminder
TimeSpan	period	Frequence period for this reminder

Returns

Type	Description
Task<IGrainReminder>	Promise for Reminder handle.

RegisterTimer(Func<Object, Task>, Object, TimeSpan, TimeSpan)

Registers a timer to send periodic callbacks to this grain.

Declaration

protected IDisposable RegisterTimer(Func<object, Task> asyncCallback, object state, TimeSpan dueTime, TimeSpan period)

Parameters

Type	Name	Description
Func<System.Object, Task>	asyncCallback	Callback function to be invoked when timr ticks.
System.Object	state	State object that will be passed as argument when calling the asyncCallback.
TimeSpan	dueTime	Due time for first timer tick.
TimeSpan	period	Period of subsequent timer ticks.

Returns

Type	Description
IDisposable	Handle for this Timer.

Remarks

This timer will not prevent the current grain from being deactivated. If the grain is deactivated, then the timer will be discarded.

Until the Task returned from the asyncCallback is resolved, the next timer tick will not be scheduled. That is to say, timer callbacks never interleave their turns.

The timer may be stopped at any time by calling the Dispose method on the timer handle returned from this call.

Any exceptions thrown by or faulted Task's returned from the asyncCallback will be logged, but will not prevent the next timer tick from being queued.

UnregisterReminder(IGrainReminder)

Unregisters a previously registered reminder.

Declaration

protected Task UnregisterReminder(IGrainReminder reminder)

Parameters

Type	Name	Description
IGrainReminder	reminder	Reminder to unregister.

Returns

Type	Description
Task	Completion promise for this operation.

Implements

IAddressable

ILifecycleParticipant<TLifecycleObservable>

Extension Methods

LoggerExtensionMethods.GetLogger(Grain, String)

LoggerExtensionMethods.GetLogger(Grain)

Orleans.Storage.GrainStorageExtensions.GetGrainStorage(Orleans.Grain, IServiceProvider)

ImmutableExt.AsImmutable<T>(T)