changkun/sched is one of the server-side repositories TopGit tracks, currently at 49 stars, written primarily in Go. ⏳ a high performance reliable task scheduling package in Go.
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
sched runs a task at a given time, keeps it across restarts, and runs it
once across every replica of your application.
It is a library, not a service. A task is a Go type that carries its own data
and its own code, so scheduling one is a function call, and the result comes
back through a future.
go get github.com/changkun/sched
Quick start
// Restore the tasks that the last run left behind. Pass an empty value of
// every task type you want back, so sched knows what to decode into.
futures, err := sched.Init("redis://127.0.0.1:6379/0", &EmailTask{})
if err != nil {
return err
}
for _, f := range futures {
fmt.Println(f.Get())
}
// Schedule a task for the time it reports.
f, err := sched.Submit(&EmailTask{To: "[email protected]", At: tomorrow})
if err != nil {
return err
}
// Get blocks until the task ran.
fmt.Println(f.Get())
// Or wait without blocking forever.
select {
case <-f.Done():
fmt.Println(f.Get())
case <-ctx.Done():
return ctx.Err()
}
sched.Stop() // when the application shuts down
Submitting an identifier that is already scheduled moves the task to the new
time instead of adding a second one, and resolves every future waiting for it.
sched.Trigger schedules a task for now, sched.Pause and sched.Resume
stop and start the scheduler, and sched.Wait blocks until nothing is queued
or running.
Writing a task
A task carries its own state, so every field it needs after a restart has to
be exported and encodable by encoding/json. sched restores the identifier
and the execution time itself.
type EmailTask struct {
To string `json:"to"`
At time.Time `json:"at"`
id string
}
func (t *EmailTask) ID() string { return t.id }
func (t *EmailTask) SetID(id string) { t.id = id }
func (t *EmailTask) Execution() time.Time { return t.At }
func (t *EmailTask) SetExecution(e time.Time) { t.At = e }
func (t *EmailTask) Timeout() time.Duration { return time.Minute }
func (t *EmailTask) RetryTime() time.Time { return time.Now().UTC().Add(time.Minute) }
func (t *EmailTask) Execute() (any, bool, error) {
if err := send(t.To); err != nil {
return nil, true, err // run again at RetryTime
}
return "sent", false, nil
}
Timeout is how long the lock that keeps two replicas apart stays alive.
sched releases it as soon as Execute returns, so the lifetime only matters
when the replica dies mid-task. Give it more than Execute normally needs: a
lifetime that expires during execution lets a second replica start the same
task, and one much longer than that keeps the task unclaimable after a crash.
A task that panics does not take the process down: the panic comes back
through the future as an error. A future always resolves. If sched refuses
to run a task, Get returns ErrTaskClaimed (another replica took it),
ErrTaskUnverifiable (its record could not be read) or ErrStopped (the
scheduler shut down first), so no caller waits for a result that cannot
arrive.
What it does for you
Survives restarts. Every scheduled task is written to Redis before it is
queued. Init brings back what did not run.
Runs once across replicas. Each task takes a Redis lock with a lifetime
of Timeout before it runs.
Retries. A task that returns an error, or asks for a retry, comes back at
RetryTime.
Returns a result.Submit and Trigger hand back a Future.
Reacts to other replicas. A replica rereads the persisted execution time
before it runs a task, and reschedules if another replica moved it.
How it works
One goroutine owns a priority queue of tasks ordered by execution time, and a
single timer serves the head of that queue. Callers never touch the queue.
Submit first persists the task, which is a round-trip to Redis, and then
hands it to the scheduler through a wait-free multi-producer queue: a fixed
number of atomic operations, with no loop and no retry, so no caller ever
waits for a lock or for another caller. The retry path uses the same queue.
Pause, Resume and Stop do not queue anything; they set an atomic counter
and drop a signal that tells the scheduler to look again. The package holds no
mutex.
Each task that comes due runs in its own goroutine, so a slow task delays
neither the scheduler nor the tasks behind it.
Submit ┐
Trigger├──▶ intake ─────────┐
retry ┘ wait-free MPSC │
▼
scheduler goroutine ──┬──▶ goroutine: lock ▸ Execute ▸ Future
Pause ┐ ▲ └──▶ goroutine: lock ▸ Execute ▸ Future
Resume ├──▶ wake signal ────┘
Stop ┘ owns the priority queue
and the one timer
Upgrading from 0.8
The 0.9 release renames most of the API. The change is mechanical.
0.8
0.9
TaskFuture
Future, plus a Done() <-chan struct{} method
Task.GetID
Task.ID
Task.GetExecution
Task.Execution
Task.SetExecution(t) (old time.Time)
Task.SetExecution(t)
Task.GetTimeout
Task.Timeout
Task.GetRetryTime
Task.RetryTime
Task.IsValidID
removed; sched skips a record that decodes to a zero value
sched/simsched
removed; this package is the fast one now
sched/tests
removed; the example tasks live in the documentation
Two behaviours changed. Submit and Trigger return ErrNotInitialized
before Init instead of panicking. A future always resolves: the paths that
used to leave a caller blocked forever now publish ErrTaskClaimed,
ErrTaskUnverifiable or ErrStopped.
Read Task.Timeout again if you copied the old comment. It said to keep the
lock shorter than the execution, which is the setting that lets two replicas
run one task.
Requirements
Go 1.27 and a Redis server. The test suite runs against an in-process Redis
and needs no server of its own.
The most recent commit recorded on changkun/sched was 2 months ago, based on the GitHub push timestamp. The repository has 4 forks — one of the better signals of community interest.
How many stars does changkun/sched have?
changkun/sched has 49 GitHub stars — refresh the page for the live number, or check github.com/changkun/sched. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What else is in the Backend space?
changkun/sched is tracked by TopGit under the Backend category, alongside 5 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What language is changkun/sched written in?
changkun/sched is written primarily in Go. GitHub's language field is based on the largest share of bytes in the default branch.
What topics is changkun/sched associated with?
GitHub's repository topics for changkun/sched: "go", "golang", "high-performance", "persistence", "scheduler". TopGit's editorial category is Backend.
Where do I read more about changkun/sched?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/changkun/sched is the definitive source.
Why is changkun/sched categorized under Backend?
TopGit places changkun/sched in the Backend category based on its GitHub topics and description (tagged: "go", "golang", "high-performance"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Want a second opinion on sched?
Ask an AI that can read this page — one click and you get its take on sched.