Class Grain
The abstract base class for all grain classes.
Namespace: Orleans
Assembly: Orleans.Core.Abstractions.dll
Syntax
public abstract class Grain : object, IAddressable, ILifecycleParticipant<IGrainLifecycle>
Constructors
| Improve this Doc View SourceGrain()
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
| Improve this Doc View SourceGrainFactory
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
| Improve this Doc View SourceDeactivateOnIdle()
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. |