Quick start

Introduction

Chrono is a scheduler library for Go. In this guide, you create a scheduler, schedule a task, cancel it when needed, and shut the scheduler down cleanly.

If the package is not installed yet, add it first:

go get go.codnect.io/chrono

Create a scheduler

Create a default scheduler when your application needs a ready-to-use scheduler with Chrono's standard runtime behavior.

package main

import (
	"context"
	"time"

	"go.codnect.io/chrono"
)

func main() {
	scheduler := chrono.NewDefaultTaskScheduler()

	startAt := time.Now().Add(2 * time.Second)
	task := scheduler.Schedule(func(ctx context.Context) {
		println("task executed")
	}, chrono.WithTime(startAt))

	time.Sleep(3 * time.Second)
	task.Cancel()

	<-scheduler.Shutdown()
}

Schedule registers work that should run at a specific time. The scheduled function receives a context.Context, so task code can follow the same context pattern as the rest of your application.

Repeat work with a delay

Use fixed delay scheduling when the next run should wait until the previous run has finished.

scheduler.ScheduleWithFixedDelay(func(ctx context.Context) {
	println("sync completed")
}, 5*time.Second)

Fixed delay is useful for polling, synchronization, cleanup, and other jobs where overlapping executions would make behavior harder to reason about.

Run on a steady interval

Use fixed rate scheduling when the interval itself matters.

scheduler.ScheduleAtFixedRate(func(ctx context.Context) {
	println("collect metrics")
}, 5*time.Second)

Fixed rate scheduling is useful for regular application work such as metrics, heartbeats, and periodic state checks.

Use a cron expression

Use cron scheduling when the task should follow calendar-based timing.

scheduler.ScheduleWithCron(func(ctx context.Context) {
	println("daily report")
}, "0 30 9 * * *", chrono.WithLocation("Europe/Istanbul"))

WithLocation tells Chrono which time zone should be used when interpreting the cron expression.

What happened?

NewDefaultTaskScheduler created a scheduler, the schedule methods registered tasks, Cancel stopped a scheduled task, and Shutdown let the application wait until the scheduler stopped.

Continue with One-shot tasks or Cron schedules when you want to choose the right schedule for a specific job.