tessl/golang-github-com-go-co-op-gocron-v2
A Golang job scheduling library that lets you run Go functions at pre-determined intervals using cron expressions, fixed durations, daily, weekly, monthly, or one-time schedules with support for distributed deployments.
one-time.mddocs/api/jobs/
One-Time Jobs
Jobs that run once (or at specific future times) then are automatically removed.
OneTimeJob
func OneTimeJob(startAt OneTimeJobStartAtOption) JobDefinitionRuns once (or at specific future times) then is automatically removed from the scheduler.
Parameters:
startAt: When to run (created with start option functions)
Errors:
ErrOneTimeJobStartDateTimePast: All start times are in the past
Start Options
func OneTimeJobStartImmediately() OneTimeJobStartAtOption
func OneTimeJobStartDateTime(start time.Time) OneTimeJobStartAtOption
func OneTimeJobStartDateTimes(times ...time.Time) OneTimeJobStartAtOptionOneTimeJobStartImmediately
Runs as soon as the executor picks it up (may have queue delay).
gocron.OneTimeJob(gocron.OneTimeJobStartImmediately())OneTimeJobStartDateTime
Runs at a specific future time.
futureTime := time.Now().Add(1 * time.Hour)
gocron.OneTimeJob(gocron.OneTimeJobStartDateTime(futureTime))OneTimeJobStartDateTimes
Runs at multiple specific times. Job is removed after all times have passed.
gocron.OneTimeJob(gocron.OneTimeJobStartDateTimes(
time.Now().Add(1*time.Hour),
time.Now().Add(2*time.Hour),
time.Now().Add(3*time.Hour),
))Examples
Run Once Immediately
j, err := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartImmediately()),
gocron.NewTask(func() {
initializeSystem()
}),
gocron.WithName("init"),
)Run at Specific Time
// Run in 1 hour
futureTime := time.Now().Add(1 * time.Hour)
j, err := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartDateTime(futureTime)),
gocron.NewTask(func() {
sendScheduledEmail()
}),
)Run at Multiple Times
// Run at 3 specific times
j, err := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartDateTimes(
time.Now().Add(1*time.Hour),
time.Now().Add(2*time.Hour),
time.Now().Add(3*time.Hour),
)),
gocron.NewTask(func() {
sendReminder()
}),
gocron.WithName("reminders"),
)Delayed Execution
// Execute after 30 seconds
delay := time.Now().Add(30 * time.Second)
j, err := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartDateTime(delay)),
gocron.NewTask(func() {
processDelayedTask()
}),
)Behavior
Automatic Removal
Jobs are automatically removed after running:
- For
StartImmediately: Removed immediately after first execution - For
StartDateTime: Removed after the single execution - For
StartDateTimes: Removed after all times have passed
Queue Delay
"Immediately" means as soon as executor picks it up. There may be a delay if:
- Other jobs are running (concurrency limits)
- Jobs are queued (using
LimitModeWait)
Past Times
For StartDateTimes, past times are ignored. At least one time must be in the future, or ErrOneTimeJobStartDateTimePast is returned.
// ERROR: all times in past
_, err := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartDateTimes(
time.Now().Add(-1*time.Hour),
time.Now().Add(-2*time.Hour),
)),
gocron.NewTask(myFunc),
)
// err == ErrOneTimeJobStartDateTimePastUse Cases
Initialization Tasks
j, _ := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartImmediately()),
gocron.NewTask(func() {
loadConfiguration()
warmupCache()
log.Println("System initialized")
}),
gocron.WithName("startup"),
)Scheduled Notifications
// Send reminder 1 hour before meeting
meetingTime := time.Date(2024, 3, 15, 14, 0, 0, 0, time.Local)
reminderTime := meetingTime.Add(-1 * time.Hour)
j, _ := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartDateTime(reminderTime)),
gocron.NewTask(func() {
sendMeetingReminder()
}),
)Multi-Stage Reminders
deadline := time.Date(2024, 3, 20, 17, 0, 0, 0, time.Local)
j, _ := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartDateTimes(
deadline.Add(-7*24*time.Hour), // 1 week before
deadline.Add(-24*time.Hour), // 1 day before
deadline.Add(-1*time.Hour), // 1 hour before
)),
gocron.NewTask(func() {
sendDeadlineReminder()
}),
)Delayed Retry
func scheduleRetry(s gocron.Scheduler, task func() error, delay time.Duration) {
s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartDateTime(
time.Now().Add(delay),
)),
gocron.NewTask(func() error {
err := task()
if err != nil {
// Retry again with exponential backoff
scheduleRetry(s, task, delay*2)
}
return err
}),
)
}Combining with Other Options
With Limited Runs
Not typically needed since OneTimeJob auto-removes, but you can combine:
j, _ := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartImmediately()),
gocron.NewTask(myFunc),
gocron.WithLimitedRuns(1), // Redundant but harmless
)With Event Listeners
j, _ := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartImmediately()),
gocron.NewTask(func() {
initializeSystem()
}),
gocron.WithEventListeners(
gocron.AfterJobRuns(func(jobID uuid.UUID, jobName string) {
log.Printf("Initialization complete: %s", jobName)
}),
),
)With Context
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
j, _ := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartImmediately()),
gocron.NewTask(func(ctx context.Context) error {
return longRunningInitialization(ctx)
}),
gocron.WithContext(ctx),
)Error Handling
All Times in Past
pastTime := time.Now().Add(-1 * time.Hour)
_, err := s.NewJob(
gocron.OneTimeJob(gocron.OneTimeJobStartDateTime(pastTime)),
gocron.NewTask(myFunc),
)
if errors.Is(err, gocron.ErrOneTimeJobStartDateTimePast) {
log.Println("Cannot schedule job in the past")
}See Also
- Duration Jobs - Repeating intervals
- Cron Jobs - Cron schedules
- Time-Based Jobs - Daily, weekly, monthly
- Timing Options - WithStartAt, WithStopAt
- Advanced Scheduling Guide - Edge cases
Install with Tessl CLI
npx tessl i tessl/golang-github-com-go-co-op-gocron-v2docs
api
examples
guides