Scheduling

​

Overview

​

Location transparency

​

Operations

• ScheduleOnce: Trigger Type: RunOnce. Behavior: Deliver a message once after a delay.
• Schedule: Trigger Type: Simple. Behavior: Deliver a message at a fixed interval (repeating).
• ScheduleWithCron: Trigger Type: Cron. Behavior: Deliver a message according to a cron expression.

​

API

• ScheduleOnce: Deliver once after the delay.
• Schedule: Deliver at a fixed interval (repeating).
• ScheduleWithCron: Cron-style scheduling.
• CancelSchedule: Cancel a scheduled message.
• PauseSchedule: Pause delivery.
• ResumeSchedule: Resume a paused schedule.
• ListSchedules: List every schedule currently known to the scheduler.

​

Schedule options

• WithReference: Set a unique ID for cancel, pause, or resume. Strongly recommended if you plan to manage the schedule later. Without it, an auto-generated UUID is used and may not be retrievable. Required for ScheduleWithCron in cluster mode; see Cluster-wide single fire below.
• WithSender: Set the sender PID for the scheduled message. Defaults to the system’s NoSender actor, so the target actor sees ctx.Sender() as that PID (compare it with system.NoSender()), not as nil.

​

Examples

// One-time delivery after 5 seconds
err := system.ScheduleOnce(ctx, &MyMessage{}, pid, 5*time.Second)

// Repeating every 10 seconds (with reference for later cancellation)
err := system.Schedule(ctx, &Heartbeat{}, pid, 10*time.Second, actor.WithReference("heartbeat-1"))

// Cron: every minute at second 0
err := system.ScheduleWithCron(ctx, &Cleanup{}, pid, "0 * * * * *", actor.WithReference("cleanup"))

// Cancel, pause, or resume
system.CancelSchedule("heartbeat-1")
system.PauseSchedule("cleanup")
system.ResumeSchedule("cleanup")

​

Pausing and resuming

​

Cron expression format

​

Field summary

• Seconds: Mandatory: YES. Allowed Values: 0-59. Allowed Special Characters: , - * /.
• Minutes: Mandatory: YES. Allowed Values: 0-59. Allowed Special Characters: , - * /.
• Hours: Mandatory: YES. Allowed Values: 0-23. Allowed Special Characters: , - * /.
• Day of month: Mandatory: YES. Allowed Values: 1-31. Allowed Special Characters: , - * ? / L W.
• Month: Mandatory: YES. Allowed Values: 1-12 or JAN-DEC. Allowed Special Characters: , - * /.
• Day of week: Mandatory: YES. Allowed Values: 1-7 or SUN-SAT. Allowed Special Characters: , - * ? / L #.
• Year: Mandatory: NO. Allowed Values: empty, 1970-. Allowed Special Characters: , - * /.

​

Special characters

• *: All values in a field (e.g., * in minutes = “every minute”).
• ?: No specific value; use when specifying one of two related fields (e.g., “10” in day-of-month, ? in day-of-week).
• -: Range of values (e.g., 10-12 in hour = “hours 10, 11, and 12”).
• ,: List of values (e.g., MON,WED,FRI in day-of-week = “Monday, Wednesday, Friday”).
• /: Increments (e.g., 0/15 in seconds = “0, 15, 30, 45”; 1/3 in day-of-month = “every 3 days from the 1st”).
• L: Last; meaning varies by field. Ranges or lists are not allowed with L.
  • Day-of-month: Last day of the month (e.g., L-3 = third to last day of the month).
  • Day-of-week: Last day of the week (7 or SAT) when alone; “last xxx day” when used after another value (e.g., 6L = “last Friday”).
• W: Nearest weekday to the given day (e.g., 15W = “nearest weekday to the 15th”). If 1W falls on Saturday, it fires Monday the 3rd. W only applies to a single day, not ranges or lists.
• #: Nth weekday of the month (e.g., 6#3 = “third Friday”; 2#1 = “first Monday”). Does not fire if that nth weekday does not exist in the month.

• L and W can be combined in day-of-month as LW = “last weekday of the month”.
• Month and day-of-week names are case-insensitive (e.g., MON = mon).

​

Cron examples

• 0 * * * * *: Every minute at second 0.
• 0 0 * * * *: Every hour at minute 0.
• 0 0 12 * * *: Every day at noon.
• 0 */5 * * * *: Every 5 minutes.
• 0 0 0 * * MON: Every Monday at midnight.
• 0 0 12 1 * *: 1st of every month at noon.
• 0 0 12 L * *: Last day of every month at noon.
• 0 0 12 ? * WED: Every Wednesday at noon.
• 0 0 12 15W * *: Nearest weekday to the 15th at noon.

​

Timezone

​

Use cases

• Heartbeats and health checks: Use Schedule with a fixed interval.
• Timeout notifications: Use ScheduleOnce to send a timeout message after a delay.
• Periodic aggregation or cleanup: Use ScheduleWithCron for daily, hourly, or custom schedules.
• Scheduled jobs: Use cron expressions for complex recurring patterns (e.g., “every weekday at 9am”).

​

Cluster-wide single fire

// Registered identically on every node in the cluster; only one node delivers per tick.
err := system.ScheduleWithCron(
    ctx, &DailyReport{}, pid, "0 0 9 * * *",
    actor.WithReference("daily-report"),
)

​

Sender and target actor

​

Errors

• ErrSchedulerNotStarted: Actor system not started; scheduler is started with the system.
• ErrScheduledReferenceNotFound: Cancel, pause, or resume called with an unknown reference, including the reference of a one-shot schedule that has already fired or of a schedule that was already canceled.
• ErrRemotingDisabled: Scheduling to a remote PID when remoting is not enabled.
• ErrScheduleReferenceRequired: ScheduleWithCron in cluster mode called without WithReference.

​

Delivery semantics

• Fire-and-forget: Scheduling does not provide built-in delivery guarantees (at-least-once or exactly-once). Ensure idempotency where needed.
• No retries: If delivery fails (e.g., actor not found), the message is not retried.
• ScheduleOnce: Delivered at most once after the delay; no further deliveries, and no delivery at all if the target is not running when the schedule fires. Once it has fired, its reference is released and can be used again.

​

Introspection

type ScheduleInfo struct {
	Reference string         // the schedule reference (user-supplied or auto-generated)
	Path      Path           // target actor path; nil for a grain schedule
	Grain     *GrainIdentity // target grain identity; nil for an actor schedule
}

for _, info := range system.ListSchedules() {
	fmt.Printf("%s -> %s\n", info.Reference, info.Path)
}