Grain Timers

​

Overview

​

API

• ScheduleOnce: Deliver once after the delay.
• Schedule: Deliver repeatedly at a fixed interval.
• ScheduleWithCron: Deliver according to a cron expression.
• CancelSchedule: Cancel a timer.

​

Timer options

• WithTimerReference: Set the timer’s reference. References are scoped to the grain; registering under a reference already in use cancels and replaces the existing timer.
• WithTimerKeepAlive: Make ticks count as passivation activity, keeping the grain alive while the timer runs. By default ticks do not reset the passivation clock.

​

Starting a timer from OnActivate

type DeviceGrain struct {
    lastSeen time.Time
}

func (g *DeviceGrain) OnActivate(ctx context.Context, props *actor.GrainProps) error {
    // check liveness every 30 seconds for as long as this grain is active
    _, err := props.Schedule(&CheckLiveness{}, 30*time.Second)
    return err
}

func (g *DeviceGrain) OnReceive(ctx *actor.GrainContext) {
    switch ctx.Message().(type) {
    case *DevicePing:
        g.lastSeen = time.Now()
        ctx.NoErr()
    case *CheckLiveness:
        if time.Since(g.lastSeen) > time.Minute {
            _ = ctx.TellActor("alerts", &DeviceOffline{})
        }
        ctx.NoErr()
    default:
        ctx.Unhandled()
    }
}

func (g *DeviceGrain) OnDeactivate(ctx context.Context, props *actor.GrainProps) error {
    // nothing to clean up: all timers are cancelled automatically
    return nil
}

​

Scheduling from OnReceive

func (g *OrderGrain) OnReceive(ctx *actor.GrainContext) {
    switch ctx.Message().(type) {
    case *PaymentStarted:
        // escalate unless the confirmation arrives within 30 seconds
        _, err := ctx.ScheduleOnce(&PaymentTimeout{}, 30*time.Second,
            actor.WithTimerReference("payment-timeout"))
        if err != nil {
            ctx.Err(err)
            return
        }
        ctx.NoErr()
    case *PaymentConfirmed:
        _ = ctx.CancelSchedule("payment-timeout")
        ctx.NoErr()
    case *PaymentTimeout:
        _ = ctx.TellGrain(g.escalations, &EscalatePayment{})
        ctx.NoErr()
    default:
        ctx.Unhandled()
    }
}

​

Semantics

​

Lifecycle

• Timers registered during OnActivate stay dormant until activation completes and are discarded when activation fails.
• All timers are cancelled when the grain deactivates: passivation, system shutdown, or a failure. OnDeactivate runs after the timers are stopped, so scheduling from that hook returns ErrGrainTimersStopped.
• A tick that is already in the mailbox when its timer is cancelled, or when the grain deactivates, is dropped instead of delivered.
• After reactivation a grain starts with no timers; re-register them in OnActivate.

​

Delivery

• Ticks are processed one at a time, serialized with the grain’s other messages. Tick handling never runs concurrently with other work on the same grain.
• Schedule fires at a fixed cadence, matching the actor scheduler: the period is measured from the previous fire time, not from the handler’s completion. A handler slower than the interval accumulates queued ticks in the mailbox; execution itself never overlaps.
• Tick handlers run with a background context: no deadline and no cancellation.
• A tick is fire-and-forget: an error reported with ctx.Err(err) is logged as a warning, and ctx.Unhandled() is logged the same way. Signal at most once per message (Err, NoErr, or Unhandled), as with any Tell-style message.
• When the mailbox is full (bounded mailboxes only), the tick is dropped and logged; interval and cron timers keep firing.

​

Passivation

• By default a tick does not reset the grain’s passivation clock: a grain that only receives timer ticks still passivates on schedule. Opt in per timer with WithTimerKeepAlive().
• Delivered ticks count as processed messages, so message-count-based passivation strategies see them.

​

Cron

• Cron expressions use the Quartz format, evaluated in the process’s local timezone.
• Unlike ActorSystem.ScheduleWithCron in cluster mode, no explicit reference is required and no cluster-wide arbitration takes place: a grain has exactly one activation cluster-wide, so each tick fires exactly once by construction.

​

Errors

• ErrGrainTimersStopped: Scheduling or cancelling while the grain is deactivating or not activated.
• ErrInvalidTimerInterval: Schedule is called with an interval that is not strictly positive.
• ErrScheduledReferenceNotFound: Cancelling an unknown reference, or a one-shot that has already fired.

​

Grain timers vs scheduling

• Who schedules: Grain timers: The grain itself. Actor scheduler: Any code holding a *PID.
• Target: Grain timers: Always the scheduling grain. Actor scheduler: Any actor, local or remote.
• Lifetime: Grain timers: The current activation. Actor scheduler: Until cancelled or the node stops.
• Wakes the target: Grain timers: Never. Actor scheduler: Delivery fails if the actor is gone.
• Cluster cron: Grain timers: No arbitration needed (single activation). Actor scheduler: Requires WithReference for single fire.