Grain lifecycle overview

Orleans grains use an observable lifecycle (See Orleans Lifecycle) for ordered activation and deactivation. This allows grain logic, system components, and application logic to be started and stopped in an ordered manner during grain activation and collection.

Stages

The pre-defined grain lifecycle stages are as follows.

public static class GrainLifecycleStage
{
    public const int First = int.MinValue;
    public const int SetupState = 1_000;
    public const int Activate = 2_000;
    public const int Last = int.MaxValue;
}

• First: First stage in a grain's lifecycle.
• SetupState: Setup grain state, before activation. For stateful grains, this is the stage where IStorage<TState>.State is loaded from storage, when IStorage.RecordExists is true.
• Activate: Stage where Grain.OnActivateAsync and Grain.OnDeactivateAsync are called.
• Last: Last stage in a grain's lifecycle.

While the grain lifecycle will be used during grain activation, since grains are not always deactivated during some error cases (such as silo crashes), applications should not rely on the grain lifecycle always being executed during grain deactivations.

Grain lifecycle participation

Application logic can participate with a grain's lifecycle in two ways:

• The grain can participate in its lifecycle.
• Components can access the lifecycle via the grain activation context (see IGrainContext.ObservableLifecycle).

• The grain can participate in its lifecycle.
• Components can access the lifecycle via the grain activation context (see IGrainActivationContext.ObservableLifecycle).

A grain always participates in its lifecycle, so application logic can be introduced by overriding the participate method.

Example participation

public override void Participate(IGrainLifecycle lifecycle)
{
    base.Participate(lifecycle);
    lifecycle.Subscribe(
        this.GetType().FullName,
        GrainLifecycleStage.SetupState,
        OnSetupState);
}

In the above example, Grain<TGrainState> overrides the Grain.Participate method to tell the lifecycle to call its OnSetupState method during the GrainLifecycleStage.SetupState stage of the lifecycle.

Components created during a grain's construction can take part in the lifecycle as well, without the addition of any special grain logic. Since the grain's context (IGrainContext), including the grain's lifecycle (IGrainContext.ObservableLifecycle), is created before the grain is created, any component injected into the grain by the container can participate in the grain's lifecycle.

Components created during a grain's construction can take part in the lifecycle as well, without the addition of any special grain logic. Since the grain's activation context (IGrainActivationContext), including the grain's lifecycle (IGrainActivationContext.ObservableLifecycle), is created before the grain is created, any component injected into the grain by the container can participate in the grain's lifecycle.

Example participation, creation, and activation

The following component participates in the grain's lifecycle when created using its factory function Create(...). This logic could exist in the component's constructor, but that risks the component being added to the lifecycle before it's fully constructed, which may not be safe.

public class MyComponent : ILifecycleParticipant<IGrainLifecycle>
{
    public static MyComponent Create(IGrainContext context)
    {
        var component = new MyComponent();
        component.Participate(context.ObservableLifecycle);
        return component;
    }

    public void Participate(IGrainLifecycle lifecycle)
    {
        lifecycle.Subscribe<MyComponent>(GrainLifecycleStage.Activate, OnActivate);
    }

    private Task OnActivate(CancellationToken ct)
    {
        // Do stuff
    }
}

public class MyComponent : ILifecycleParticipant<IGrainLifecycle>
{
    public static MyComponent Create(IGrainActivationContext context)
    {
        var component = new MyComponent();
        component.Participate(context.ObservableLifecycle);
        return component;
    }

    public void Participate(IGrainLifecycle lifecycle)
    {
        lifecycle.Subscribe<MyComponent>(GrainLifecycleStage.Activate, OnActivate);
    }

    private Task OnActivate(CancellationToken ct)
    {
        // Do stuff
    }
}

By registering the example component in the service container using its Create(...) factory function, any grain constructed with the component as a dependency will have the component taking part in its lifecycle without any special logic in the grain.

Register component in container

services.AddTransient<MyComponent>(sp =>
    MyComponent.Create(sp.GetRequiredService<IGrainContext>());

services.AddTransient<MyComponent>(sp =>
    MyComponent.Create(sp.GetRequiredService<IGrainActivationContext>());

Grain with component as a dependency

public class MyGrain : Grain, IMyGrain
{
    private readonly MyComponent _component;

    public MyGrain(MyComponent component)
    {
        _component = component;
    }
}