Concurrency Control

Guide to controlling concurrent job execution in gocron.

Overview

Gocron provides two levels of concurrency control:

1. Job-level: Prevent a specific job from running concurrently with itself
2. Scheduler-level: Limit total concurrent jobs across all jobs

Singleton Mode

Prevent a job from running concurrently with itself using WithSingletonMode.

LimitModeReschedule

Skip overlapping runs. Best for idempotent jobs.

j, _ := s.NewJob(
    gocron.DurationJob(30*time.Second),
    gocron.NewTask(healthCheck),
    gocron.WithSingletonMode(gocron.LimitModeReschedule),
)

Use cases:

• Health checks
• Metrics collection
• Cache refresh
• Status polling

LimitModeWait

Queue overlapping runs. All runs execute sequentially.

j, _ := s.NewJob(
    gocron.DurationJob(30*time.Second),
    gocron.NewTask(processQueue),
    gocron.WithSingletonMode(gocron.LimitModeWait),
)

Use cases:

• Queue processing
• Database migrations
• Sequential workflows
• Financial transactions

Detailed guide: Singleton Mode

Global Limits

Limit total concurrent jobs across all jobs using scheduler-level options.

s, _ := gocron.NewScheduler(
    gocron.WithLimitConcurrentJobs(3, gocron.LimitModeReschedule),
)

Only 3 jobs run concurrently across all scheduled jobs.

Detailed guide: Scheduler Limits

Interval Calculation

Control when next run is calculated:

• From start time (default): Predictable intervals
• From completion time: Guaranteed rest period

j, _ := s.NewJob(
    gocron.DurationJob(5*time.Minute),
    gocron.NewTask(slowOperation),
    gocron.WithIntervalFromCompletion(), // 5min rest after completion
)

Detailed guide: Interval Calculation

Decision Matrix

Monitoring

Track concurrency events using SchedulerMonitor:

type myMonitor struct{}

func (m *myMonitor) ConcurrencyLimitReached(limitType string, job gocron.Job) {
    log.Printf("Limit reached: %s for job %s", limitType, job.Name())
}

s, _ := gocron.NewScheduler(
    gocron.WithSchedulerMonitor(&myMonitor{}),
)

See Also

• Singleton Mode Guide - Detailed job-level control
• Scheduler Limits Guide - Global concurrency limits
• Interval Calculation Guide - Timing behavior
• API: Concurrency Options - Full API reference