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 start and stop in an ordered manner during grain activation and collection.

Memory-based activation shedding

Memory-based activation shedding automatically deactivates grain activations when the silo is under memory pressure. This helps prevent out-of-memory conditions by intelligently removing grains from memory based on their activity patterns.

How it works

When enabled, Orleans monitors memory usage and begins deactivating grains when usage exceeds the configured threshold:

1. Orleans polls memory usage at a configurable interval (default: 5 seconds)
2. When memory usage exceeds MemoryUsageLimitPercentage, Orleans begins deactivating grains
3. Orleans prioritizes deactivating older and less-recently-used grains first
4. Deactivation continues until memory usage falls below MemoryUsageTargetPercentage

Configuration

Configure memory-based activation shedding using GrainCollectionOptions:

builder.Configure<GrainCollectionOptions>(options =>
{
    // Enable memory-based activation shedding
    options.EnableActivationSheddingOnMemoryPressure = true;

    // Memory usage percentage (0-100) at which grain collection triggers
    options.MemoryUsageLimitPercentage = 80; // default: 80

    // Target memory usage percentage to reach after collection
    options.MemoryUsageTargetPercentage = 75; // default: 75

    // How often to poll memory usage
    options.MemoryUsagePollingPeriod = TimeSpan.FromSeconds(5); // default: 5s
});

GrainCollectionOptions properties

Best practices

• Set thresholds conservatively: Leave headroom between MemoryUsageTargetPercentage and MemoryUsageLimitPercentage to avoid oscillation
• Monitor collection metrics: Track grain deactivations to understand the impact on your workload
• Consider grain importance: Critical grains can extend their lifetime using timers with KeepAlive = true or by receiving periodic calls
• Test under load: Verify behavior under production-like memory conditions

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

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

Components created during a grain's construction can also participate in the lifecycle without adding any special grain logic. Since Orleans creates the grain's context (IGrainContext), including its lifecycle (IGrainContext.ObservableLifecycle), before creating the grain, any component injected into the grain by the container can participate in the grain's lifecycle.

Components created during a grain's construction can also participate in the lifecycle without adding any special grain logic. Since Orleans creates the grain's activation context (IGrainActivationContext), including its lifecycle (IGrainActivationContext.ObservableLifecycle), before creating the grain, any component injected into the grain by the container can participate in the grain's lifecycle.

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
    }
}

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

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

Grain migration

Grain migration allows grain activations to move from one silo to another while preserving their in-memory state. This enables load balancing and cluster optimization without losing grain state. The migration process involves:

1. Dehydration: Serializing the grain's state on the source silo before deactivation
2. Transfer: Sending the serialized state to the target silo
3. Rehydration: Restoring the grain's state on the new activation before OnActivateAsync is called

When migration occurs

Migration can occur in several scenarios:

• Application-initiated: A grain can request migration by calling this.MigrateOnIdle()
• Activation repartitioner: Automatically collocates frequently communicating grains to optimize call locality (experimental)
• Activation rebalancer: Distributes activations to balance load across silos (experimental)

Implementing migration support

Grains can participate in migration by implementing IGrainMigrationParticipant:

public interface IGrainMigrationParticipant
{
    void OnDehydrate(IDehydrationContext dehydrationContext);
    void OnRehydrate(IRehydrationContext rehydrationContext);
}

Option 1: Implement IGrainMigrationParticipant directly

For grains with custom in-memory state that should be preserved during migration:

public class MyMigratableGrain : Grain, IMyGrain, IGrainMigrationParticipant
{
    private int _cachedValue;
    private string _sessionData;

    public void OnDehydrate(IDehydrationContext dehydrationContext)
    {
        // Save state before migration
        dehydrationContext.TryAddValue("cached", _cachedValue);
        dehydrationContext.TryAddValue("session", _sessionData);
    }

    public void OnRehydrate(IRehydrationContext rehydrationContext)
    {
        // Restore state after migration
        rehydrationContext.TryGetValue("cached", out _cachedValue);
        rehydrationContext.TryGetValue("session", out _sessionData);
    }
}

Option 2: Use Grain<TState> or IPersistentState<T>

Grains using Grain<TGrainState> or IPersistentState<TState> automatically support migration. Their state is serialized and restored without additional code:

// Automatic migration support via Grain<TState>
public class MyStatefulGrain : Grain<MyGrainState>, IMyGrain
{
    public Task UpdateValue(int value)
    {
        State.Value = value;
        return WriteStateAsync();
    }
}

// Automatic migration support via IPersistentState<T>
public class MyOtherGrain : Grain, IMyGrain
{
    private readonly IPersistentState<MyGrainState> _state;

    public MyOtherGrain(
        [PersistentState("state", "storage")] IPersistentState<MyGrainState> state)
    {
        _state = state;
    }
}

Triggering migration

A grain can request migration to a new silo:

public class MyGrain : Grain, IMyGrain
{
    public Task RequestMigration()
    {
        // Request migration when the grain becomes idle
        this.MigrateOnIdle();
        return Task.CompletedTask;
    }
}

You can also specify a preferred target silo using placement hints:

public Task MigrateToSilo(SiloAddress targetSilo)
{
    RequestContext.Set(IPlacementDirector.PlacementHintKey, targetSilo);
    this.MigrateOnIdle();
    return Task.CompletedTask;
}

Preventing automatic migration

Use the ImmovableAttribute to prevent automatic migration by the repartitioner or rebalancer:

// Prevent all automatic migration
[Immovable]
public class MyImmovableGrain : Grain, IMyGrain { }

// Prevent only repartitioner migration
[Immovable(ImmovableKind.Repartitioner)]
public class MyPartiallyImmovableGrain : Grain, IMyGrain { }

The ImmovableKind enum provides these options:

Non-migratable grain types

The following grain types cannot be migrated:

• Client grains
• System targets
• Grain services
• Stateless worker grains