Duration Jobs

Jobs that run at fixed or random intervals.

DurationJob

func DurationJob(duration time.Duration) JobDefinition

Runs at fixed intervals. Interval is measured from scheduled start time (not completion time) unless WithIntervalFromCompletion is used.

Parameters:

• duration: Must be > 0

Errors:

• ErrDurationJobIntervalZero: duration is exactly 0
• ErrDurationJobIntervalNegative: duration is < 0

Examples:

// Every 5 minutes
gocron.DurationJob(5 * time.Minute)

// Every hour
gocron.DurationJob(time.Hour)

// Every 30 seconds
gocron.DurationJob(30 * time.Second)

Interval Calculation

By default, interval is from scheduled start:

• Job scheduled at 09:00, takes 2 minutes → next run at 09:05

With WithIntervalFromCompletion():

• Job scheduled at 09:00, takes 2 minutes → next run at 09:07 (5 min after completion)

See WithIntervalFromCompletion.

DurationRandomJob

func DurationRandomJob(minDuration, maxDuration time.Duration) JobDefinition

Runs at random intervals between min and max. Useful for preventing thundering herd in distributed systems.

Parameters:

• minDuration: Minimum interval, must be > 0
• maxDuration: Maximum interval, must be > minDuration

Errors:

• ErrDurationRandomJobPositive: min or max ≤ 0
• ErrDurationRandomJobMinMax: min ≥ max

Examples:

// Random interval between 4-6 minutes (5 min median ± 1 min jitter)
gocron.DurationRandomJob(4*time.Minute, 6*time.Minute)

// Random interval between 1-10 seconds
gocron.DurationRandomJob(time.Second, 10*time.Second)

Use Cases

• Load distribution in clustered systems
• Preventing synchronized spikes
• Jittered retry backoff

Usage Examples

Basic Duration Job

j, err := s.NewJob(
    gocron.DurationJob(5*time.Minute),
    gocron.NewTask(func() {
        fmt.Println("Running every 5 minutes")
    }),
)

With Interval From Completion

j, err := s.NewJob(
    gocron.DurationJob(5*time.Minute),
    gocron.NewTask(func() {
        doSlowWork() // variable duration
    }),
    gocron.WithIntervalFromCompletion(),
)
// Ensures 5 minutes rest between runs

Random Interval for Load Distribution

// Multiple instances won't synchronize
j, err := s.NewJob(
    gocron.DurationRandomJob(4*time.Minute, 6*time.Minute),
    gocron.NewTask(func() {
        pollExternalAPI()
    }),
)

High-Frequency Task

j, err := s.NewJob(
    gocron.DurationJob(100*time.Millisecond),
    gocron.NewTask(func() {
        checkSystemHealth()
    }),
    gocron.WithSingletonMode(gocron.LimitModeReschedule),
)

When to Use

Use DurationJob when:

• You need fixed intervals (every 5 minutes)
• Timing precision is important
• Jobs should run at predictable times

Use DurationRandomJob when:

• Running in distributed/clustered environment
• Want to avoid thundering herd
• Load distribution is more important than timing precision

See Also

• Cron Jobs - Complex schedules with cron expressions
• Time-Based Jobs - Daily, weekly, monthly schedules
• One-Time Jobs - Run once then remove
• Concurrency Options - Control overlapping runs
• Timing Options - Start/stop times