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.
concurrency.mddocs/api/options/
Concurrency Options
Options for controlling concurrent job execution.
WithSingletonMode
func WithSingletonMode(mode LimitMode) JobOption
type LimitMode int
const (
LimitModeReschedule LimitMode = 1
LimitModeWait LimitMode = 2
)Prevents a job from running concurrently with itself.
Modes:
- LimitModeReschedule: Skip overlapping runs; reschedule for next time
- LimitModeWait: Queue overlapping runs; execute when current completes
// Skip overlapping runs
j, _ := s.NewJob(
gocron.DurationJob(30*time.Second),
gocron.NewTask(func() {
time.Sleep(time.Minute) // takes longer than interval
}),
gocron.WithSingletonMode(gocron.LimitModeReschedule),
)
// Runs at: 0s, 60s, 120s (skips 30s, 90s)// Queue overlapping runs
j, _ := s.NewJob(
gocron.DurationJob(30*time.Second),
gocron.NewTask(func() {
time.Sleep(time.Minute)
}),
gocron.WithSingletonMode(gocron.LimitModeWait),
)
// Queues runs at 30s, 90s; executes sequentiallyWhen to use:
- Reschedule: Idempotent jobs where missing executions is acceptable (health checks, metrics)
- Wait: Sequential jobs where every execution matters (queue processing, migrations)
See Concurrency Guide.
WithLimitConcurrentJobs
Available at scheduler level via WithLimitConcurrentJobs(limit, mode). See Creating Schedulers.
WithIntervalFromCompletion
func WithIntervalFromCompletion() JobOptionCalculates next run from job completion time instead of scheduled start time. Only applies to DurationJob and DurationRandomJob.
Without this option (default):
- Job scheduled at 09:00, takes 2 minutes
- Next run: 09:05 (5 min from start)
- Rest period: 3 minutes
With this option:
- Job scheduled at 09:00, takes 2 minutes
- Next run: 09:07 (5 min from completion at 09:02)
- Rest period: 5 minutes
j, _ := s.NewJob(
gocron.DurationJob(5*time.Minute),
gocron.NewTask(func() {
doSlowWork() // variable duration
}),
gocron.WithIntervalFromCompletion(),
)Uses:
- Rate limiting: Ensure fixed rest between executions
- Resource-intensive jobs: Guarantee downtime
- Variable-duration jobs: Maintain consistent pacing
Interaction with singleton mode: Queued runs also respect this option (each starts N minutes after previous completion).
Usage Examples
Prevent Concurrent Execution
j, _ := s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(func() {
// Long-running database backup
backupDatabase()
}),
gocron.WithSingletonMode(gocron.LimitModeReschedule),
)Queue Sequential Processing
j, _ := s.NewJob(
gocron.DurationJob(30*time.Second),
gocron.NewTask(func() {
processQueueItem()
}),
gocron.WithSingletonMode(gocron.LimitModeWait),
)Rate-Limited API Calls
j, _ := s.NewJob(
gocron.DurationJob(5*time.Second),
gocron.NewTask(func() {
callExternalAPI() // rate limit: 1 call per 5 seconds
}),
gocron.WithIntervalFromCompletion(),
gocron.WithSingletonMode(gocron.LimitModeReschedule),
)Resource-Intensive Task
j, _ := s.NewJob(
gocron.DurationJob(10*time.Minute),
gocron.NewTask(func() {
// CPU-heavy task, needs cooldown
processLargeDataset()
}),
gocron.WithIntervalFromCompletion(), // Ensure 10 min rest after completion
gocron.WithSingletonMode(gocron.LimitModeReschedule),
)Global Concurrency Limit
s, _ := gocron.NewScheduler(
gocron.WithLimitConcurrentJobs(3, gocron.LimitModeReschedule),
)
// Only 3 jobs run concurrently across all jobs
for i := 0; i < 10; i++ {
s.NewJob(
gocron.DurationJob(time.Second),
gocron.NewTask(func() {
time.Sleep(5 * time.Second)
}),
)
}
s.Start()Comparison: Reschedule vs Wait
| Aspect | LimitModeReschedule | LimitModeWait |
|---|---|---|
| Behavior | Skip if running | Queue if running |
| Missed runs | Lost | Preserved |
| Use case | Idempotent tasks | Sequential tasks |
| Examples | Health checks, metrics | Queue processing, migrations |
See Also
- Singleton Mode Guide - Detailed explanation
- Global Limits - Scheduler-level limits
- Timing Options - Start/stop times
- Duration Jobs - WithIntervalFromCompletion usage
Install with Tessl CLI
npx tessl i tessl/golang-github-com-go-co-op-gocron-v2@2.19.1docs
api
examples
guides