Scheduling

​

Overview

​

Location Transparency

​

Operations

​

API

​

Schedule Options

​

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")

​

Cron Expression Format

​

Field Summary

​

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

​

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

​

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 exactly once after the delay; no further deliveries.

​

Introspection

type ScheduleInfo struct {
	Reference string // the schedule reference (user-supplied or auto-generated)
	Path      Path   // target actor path
}

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