time.Ticker — Middle Level¶

Table of Contents¶

1. Introduction
2. What the Middle Level Adds
3. Reset Semantics from Go 1.15 Onwards
4. Monotonic Clock Guarantees
5. Drift versus Jitter
6. The Canonical select Loop
7. Combining Ticker with a Done Channel
8. Combining Ticker with context.Context
9. Dynamic Intervals at Runtime
10. Stop on Exit: The Discipline
11. Slow Consumers and Dropped Ticks
12. Jittered Tickers
13. Drift-Corrected Loops
14. Ticker Versus time.After in a Loop
15. Ticker Versus time.AfterFunc
16. Testability: Mocking and Fake Clocks
17. Patterns from Production Codebases
18. Composition with errgroup
19. Coalescing Ticks with Pending Work
20. Memory Behaviour and Allocation Profile
21. Observability Hooks
22. Ticker Wrappers Worth Building Once
23. Interaction with the Garbage Collector
24. Common Mistakes at the Middle Level
25. Idiomatic Refactors
26. Worked Example: A Cache Janitor
27. Worked Example: An Adaptive Poller
28. Worked Example: A Health Reporter
29. Cross-Platform Considerations
30. Reading the Standard Library
31. Self-Assessment
32. Summary

Introduction¶

You have already used time.NewTicker, the t.C channel, and defer t.Stop() in a for { select { } } loop. That is the junior level. The middle level is where you start treating the ticker as a real concurrency primitive whose semantics matter in production.

At the middle level you should be able to:

• Explain when Reset is safe to call and when it is racy.
• State what the monotonic clock guarantees and why a ticker survives system clock jumps.
• Distinguish drift (cumulative timing error) from jitter (per-tick variance) and explain why those are different bugs.
• Write a cancellable ticker loop that integrates with context.Context correctly.
• Change a ticker's interval at runtime without losing ticks or leaking goroutines.
• Recognise why time.After in a for loop is a leak shape and how NewTicker avoids it.
• Reason about what happens when the consumer is slower than the ticker rate, and decide between dropping ticks, queueing them, or applying backpressure.

The file is opinionated. Where the standard library leaves you choices, this document recommends one and explains why. The recommendations are based on the Go 1.20+ standard library and on patterns that show up across the largest open-source Go code bases. Go 1.15 introduced safe Reset, Go 1.23 changed the channel-buffer and GC behaviour of timers — both transitions matter and are called out where relevant.

A note on scope: every code snippet in this file compiles on Go 1.20 or newer. Where a fragment relies on Go 1.23 semantics, the prose says so explicitly. Examples are written for clarity over cleverness; they show the right shape, not the most condensed version.

What the Middle Level Adds¶

Junior-level ticker code answers four questions:

1. How do I construct one?
2. How do I read from C?
3. How do I stop it?
4. How do I exit the loop?

Middle-level code answers eight more:

1. How do I change the interval after construction?
2. How do I make sure the ticker survives system clock changes?
3. How do I measure and bound timing error?
4. How do I make the loop cancellable from the outside?
5. How do I avoid silently dropping ticks under load?
6. How do I avoid the "thundering herd" problem when many tickers fire at once?
7. How do I write tests that do not wait real wall-clock time?
8. How do I prove the ticker stops when the surrounding component is disposed?

This document walks through each question with code, then revisits them in the Self-Assessment at the end.

Reset Semantics from Go 1.15 Onwards¶

Reset(d time.Duration) changes a ticker's interval to d and arranges for the next tick to fire after d from the moment of the call. It was added to *time.Ticker in Go 1.15. Before 1.15 the only safe way to change the period was to Stop the old ticker and NewTicker a fresh one — that idiom still compiles but is no longer required.

Why Reset Exists¶

A ticker is backed by an entry in the runtime's timer heap. Stop removes it; NewTicker allocates a new one. Re-allocating churns through the heap on every interval change, which is wasteful in code that adapts rapidly — for example a poll that backs off when results are empty and speeds up when they are not.

Reset mutates the existing heap entry in place. No allocation, no new channel, same t.C.

t := time.NewTicker(time.Second)
defer t.Stop()

// later: speed it up
t.Reset(100 * time.Millisecond)

// later: slow it down
t.Reset(5 * time.Second)

The same t.C is reused; downstream consumers do not need to be rewired.

What Reset Does Not Guarantee¶

The documentation reads: "Reset stops a ticker and resets its period to the specified duration. The next tick will arrive after the new period elapses." That sounds unambiguous, but it leaves three subtle questions:

1. What happens to a tick that was already pending on t.C when Reset was called?
2. Is Reset safe to call concurrently with a receive from t.C?
3. Can you Reset a ticker that has been Stop-ped?

The answers, on current Go, are:

1. A pending tick may or may not still be on the channel after Reset returns. The standard library does not drain t.C for you. If you care, you must drain it yourself (see below).
2. Reset and receiving from t.C are independently safe — the runtime synchronises them internally. They are not, however, atomic: a receive may complete just before the Reset takes effect, observing the old period. If you require that the next received tick be a "post-Reset" tick, drain first.
3. Yes. Calling Reset on a stopped ticker re-arms it. This was clarified in Go 1.23. Before 1.23 the documentation was vague on this point and some code defensively allocated a new ticker; that defensive allocation is no longer necessary.

The Drain-Before-Reset Pattern¶

If your code path depends on "the next tick must be at least d after Reset," drain a possibly-pending tick first:

func resetTicker(t *time.Ticker, d time.Duration) {
    if !t.Stop() {
        select {
        case <-t.C:
        default:
        }
    }
    t.Reset(d)
}

This mirrors the well-known idiom for *time.Timer. For a Ticker, Stop returns false if the ticker has already been stopped, so the helper is most useful when you cannot tell whether Stop was already called. In practice, the simple form

select {
case <-t.C:
default:
}
t.Reset(d)

is enough for most ticker use because tickers fire repeatedly — a stale tick in the channel is almost always benign. The drain is only critical when consuming an old tick would do harm, for example if you are using the tick to decide whether to start an expensive operation.

Reset Does Not Reset the Phase Strictly¶

Important nuance: Reset(d) schedules the next tick d from now, not aligned with any previous phase. If you had a 1-second ticker that fired at t=0.0, t=1.0, t=2.0, and you Reset(time.Second) at t=2.4, the next tick fires at t=3.4, then t=4.4, t=5.4, and so on. The phase shifts by 0.4 seconds and stays shifted.

If you need phase-aligned reset behaviour — for example "always fire at the top of the second" — you must implement that yourself with a one-shot time.NewTimer to absorb the partial interval, then a new ticker.

func alignedTicker(period time.Duration) *time.Ticker {
    now := time.Now()
    wait := period - now.Sub(now.Truncate(period))
    time.Sleep(wait)
    return time.NewTicker(period)
}

This is not a Reset use case — it is an alignment pattern that uses Stop and NewTicker. The point is that Reset is for changing the period, not for re-phasing.

Reset on a Ticker That Has Never Fired¶

Reset may be called on a freshly-constructed ticker before any tick has been observed. It simply changes the pending wake-up time. This is convenient for builders that construct a ticker with a placeholder duration and adjust based on config loaded later:

t := time.NewTicker(time.Hour) // placeholder, will be replaced
cfg := loadConfig()
t.Reset(cfg.Interval)

The placeholder allocation is cheap and the code reads more naturally than nil-checking and conditional construction.

Calling Reset After Stop¶

Post Go 1.23 (and in practice on most earlier versions too) you may call Reset on a Stop-ed ticker to re-arm it. The internal timer entry is re-added to the heap. This is useful for pause/resume patterns:

type PausableTicker struct {
    t      *time.Ticker
    period time.Duration
}

func NewPausableTicker(period time.Duration) *PausableTicker {
    pt := &PausableTicker{t: time.NewTicker(period), period: period}
    return pt
}

func (pt *PausableTicker) Pause()  { pt.t.Stop() }
func (pt *PausableTicker) Resume() { pt.t.Reset(pt.period) }
func (pt *PausableTicker) C() <-chan time.Time { return pt.t.C }
func (pt *PausableTicker) Close() { pt.t.Stop() }

Before 1.23, Reset after Stop was documented as "may or may not work, depending on whether any drained tick was on the channel." In modern Go this round-trip is reliable.

Reset and Negative or Zero Durations¶

Reset(0) and Reset(d) for negative d panic. This mirrors NewTicker(0). The runtime cannot schedule a non-positive interval — there is no "fire as fast as possible" mode. If you want unbounded throughput, do not use a ticker; use a tight loop or a buffered channel.

t.Reset(0) // panic: non-positive interval for Ticker.Reset

Wrap user-supplied durations:

func safeReset(t *time.Ticker, d time.Duration) {
    if d <= 0 {
        d = time.Millisecond // or whatever floor makes sense
    }
    t.Reset(d)
}

When Reset Is the Wrong Tool¶

If the new period is dramatically different from the old, and you also want to discard any pending tick, recreating the ticker is just as readable and avoids one corner case (a pending tick observed after the reset). For a tight inner loop that adapts every iteration, Reset saves an allocation per change. For a one-time adjustment, Stop + NewTicker is a fine alternative.

The decision tree:

• High-frequency changes (every iteration of an adaptive loop): use Reset.
• One-time mode change (e.g. switch from "boot" interval to "steady-state" interval): either is fine, Reset is one line shorter.
• The new period is very different from the old, and stale ticks would mislead the consumer: Stop + drain + NewTicker, or Stop + drain + Reset.
• Tests that simulate clock jumps: prefer a fake clock library, do not abuse Reset.

Monotonic Clock Guarantees¶

time.NewTicker uses the runtime's monotonic clock for scheduling. The monotonic clock has three properties that distinguish it from the wall clock:

1. It never goes backward. Wall-clock time can be set backward by NTP correction or by a sysadmin running date -s. Monotonic time cannot.
2. It is unaffected by leap seconds. Linux's CLOCK_MONOTONIC does not see leap second insertions.
3. It is calibrated against a stable hardware source. Modern OSes use TSC (on x86) or a similar invariant counter, scaled by the kernel.

For a ticker, this means the fire times are determined by elapsed monotonic time since the previous fire, not by the wall clock. If the system clock jumps forward by an hour, your 1-second ticker does not suddenly catch up by firing 3600 times — it keeps firing once per real second.

Why This Matters¶

Consider a heartbeat that sends "alive" every 5 seconds. If you implemented it with a comparison to time.Now() against a wall-clock baseline, an NTP correction could either skip heartbeats (clock jumped forward) or send a burst (clock jumped backward). Tickers using monotonic time are immune.

Verifying the Monotonic Guarantee¶

You can observe the monotonic clock in the result of time.Now() by formatting it: when a time.Time carries monotonic data the String() form includes an m=... suffix. The value sent on t.C carries monotonic data, so:

t := time.NewTicker(time.Second)
defer t.Stop()
fmt.Println(<-t.C) // 2024-01-02 15:04:05.001 +0000 UTC m=+1.001

That m=+1.001 part is the monotonic reading: 1.001 seconds after the program started. The receive returns the absolute time with the monotonic component attached.

When the Monotonic Component Is Stripped¶

Operations that strip monotonic data:

• Marshalling/unmarshalling through JSON, gob, or text.
• t.Round(0) and t.Truncate(d) (for some d).
• Calling time.Date(...) directly.

If you subtract two times to compute elapsed duration and one of them has been stripped of monotonic data, you fall back to wall-clock comparison and your "elapsed time" can be wrong by minutes. For elapsed-time computations always use values that carry monotonic data, ideally values from time.Now() or <-t.C in the same process.

Ticker Versus Wall-Clock Cron¶

Tickers are great for "every N seconds." They are not the tool for "every day at 02:00." For wall-clock-aligned schedules use a cron library (github.com/robfig/cron) or build a custom loop that sleeps until the next aligned wall-clock time.

If you naively use a 24-hour ticker, the drift accumulates across days (because intervals do not align to wall-clock midnight) and a leap second can offset the trigger.

Drift versus Jitter¶

Two timing imperfections look similar at a glance but have different causes and different remedies.

Drift¶

Drift is cumulative timing error. A 1-second ticker that fires at 1.001s, 2.002s, 3.003s, ..., is drifting by ~1ms per tick. After an hour it is 3.6 seconds behind. Each tick is roughly evenly spaced, but the absolute positions drift.

Causes:

• The runtime cannot guarantee a wake-up at exactly t = N * period because the scheduler has finite resolution.
• A heavily loaded system delays the goroutine waking on the tick.
• Code in the handler runs longer than the period, pushing each subsequent fire further out.

Drift is typically not what time.Ticker produces: the ticker schedules each tick relative to the previous scheduled time, not the previous delivered time. So if the consumer is slow, the runtime still maintains the intended schedule, dropping ticks rather than delaying them. (More on dropping below.)

Jitter¶

Jitter is random per-tick variance. The mean fire time is right, but individual ticks are noisy: 1.000s, 1.020s, 0.990s, 1.005s, ... around an expected period of 1.0s.

Causes:

• Scheduler preemption.
• GC pauses.
• CPU contention.
• OS scheduler granularity (Linux's CONFIG_HZ).

Jitter is a fact of life on any non-real-time OS. For most ticker uses (heartbeats, polls, cache flushes) sub-millisecond jitter is irrelevant. For latency-sensitive use (audio rendering, market data) you need a dedicated real-time scheduler — time.Ticker is not it.

Detecting Drift vs Jitter¶

Record the time of every tick over a long run. Compute differences:

const period = 100 * time.Millisecond
t := time.NewTicker(period)
defer t.Stop()

var last time.Time
for range t.C {
    now := time.Now()
    if !last.IsZero() {
        d := now.Sub(last)
        fmt.Printf("delta=%v drift_per_tick=%v\n", d, d-period)
    }
    last = now
}

If the deltas are stochastic around the target period, you have jitter. If the deltas slope or cluster systematically away from the period, you have drift.

The Subtle Difference Inside the Runtime¶

The runtime schedules ticks based on a when field stored in the timer entry. After firing, the when is incremented by the period for the next tick. This is intended-time scheduling, not "now + period." That eliminates drift by design — but only as long as the consumer drains the channel quickly enough that the runtime can keep up.

If the consumer is slower than the period, the runtime drops ticks rather than queueing them. The buffer of t.C is 1 (this is true both before and after Go 1.23, though the semantics around buffer 1 are subtly different — see the senior file). When the buffer is full, the runtime skips sending without blocking. The consumer's perceived rate falls; its perceived per-tick interval grows beyond the period.

So: a "drifting" ticker observed in user code almost always means the consumer cannot keep up. The cure is not to "fix the ticker"; it is to either speed up the consumer, increase the period, or add explicit backpressure.

Tolerances by Application¶

time.Ticker is right for monitoring, polling, batching, and slow human-facing tasks. It is wrong for hard real-time work.

The Canonical select Loop¶

The shape every middle-level ticker loop takes:

func Loop(ctx context.Context, period time.Duration) {
    t := time.NewTicker(period)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            return
        case now := <-t.C:
            doWork(now)
        }
    }
}

Five rules to memorise:

1. Cancellation case is listed first. It is convention, not requirement; select does not guarantee a priority order if both are ready, but listing ctx.Done() first signals intent and aids review.
2. defer t.Stop() is on the line after NewTicker. Always. Even on a goroutine that you "know" will exit on its own. If you ever refactor the exit path, the deferred Stop survives.
3. No time.After inside the loop body. A time.After(d) in a select allocates a new timer per iteration that is not cleaned up until it fires. Use the long-lived ticker.
4. No range t.C. Range on t.C works only if you have a way to break out of the range; with a ticker that has no exit path of its own, you would need to call Stop from outside and rely on the loop never noticing — which is brittle. Use select.
5. The handler should be fast. If doWork(now) can block, wrap it in a goroutine or apply a timeout. A tick that takes longer than the period silently starves later ticks.

Why ctx.Done() First¶

The position does not change semantics — select chooses randomly among ready cases. The custom is to put the exit case first as documentation: anyone reading the loop sees the cancellation path before the work path, which is the order the loop reasons about responsiveness.

A reviewer scanning the loop wants to verify:

1. Will the loop exit when asked?
2. What does it do per tick?

In that order. Putting ctx.Done() first matches the order of those questions.

Variants Worth Knowing¶

A loop that consumes from a queue and runs periodic work:

func Loop(ctx context.Context, period time.Duration, in <-chan Item) {
    t := time.NewTicker(period)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            return
        case item := <-in:
            process(item)
        case <-t.C:
            flush()
        }
    }
}

The select picks whichever case is ready. If multiple are ready it picks one randomly. This is fine: occasional unfairness over many iterations averages out.

A loop with multiple periodic actions on different cadences:

func Loop(ctx context.Context) {
    fast := time.NewTicker(100 * time.Millisecond)
    slow := time.NewTicker(time.Second)
    defer fast.Stop()
    defer slow.Stop()
    for {
        select {
        case <-ctx.Done():
            return
        case <-fast.C:
            doFastThing()
        case <-slow.C:
            doSlowThing()
        }
    }
}

Each ticker is independent and stops independently. The loop drains whichever fires first.

A loop that waits forever for cancellation between ticks (no work cadence — useful for "do something every N seconds OR when nudged"):

func Loop(ctx context.Context, period time.Duration, nudge <-chan struct{}) {
    t := time.NewTicker(period)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            return
        case <-t.C:
        case <-nudge:
        }
        doWork()
    }
}

Here both t.C and nudge lead to the same action. The action is outside the select, so any path falls through to it. This is the cleanest expression of "every N seconds, or sooner if poked."

What Not To Do¶

A loop with no exit path:

for now := range t.C {
    process(now)
}

If the surrounding goroutine has no way to break, this is a leak. The Stop from outside makes t.C no longer receive — but range on a non-closed channel that simply stops sending blocks forever on the next iteration. Stop does not close t.C. The range will block on receive forever.

This is the single most common ticker-related leak in Go code review. Always use select with an explicit exit case.

A loop that ignores the value:

for {
    <-t.C
    doWork()
}

Works but is unstyled — you cannot add a second case later without restructuring. Always prefer the select form so the loop is extensible.

A loop that nests goroutines per tick without bounding them:

for range t.C {
    go heavyWork() // unbounded fan-out
}

If heavyWork takes longer than period, you accumulate goroutines forever. Either bound the in-flight count or run heavyWork synchronously.

Combining Ticker with a Done Channel¶

context.Context is the modern way to cancel ticker loops, but a plain done chan struct{} is still seen in older code, in libraries that pre-date contexts, and in low-level packages that intentionally avoid the context dependency.

The shape:

type Worker struct {
    done chan struct{}
}

func NewWorker() *Worker {
    w := &Worker{done: make(chan struct{})}
    go w.run()
    return w
}

func (w *Worker) run() {
    t := time.NewTicker(time.Second)
    defer t.Stop()
    for {
        select {
        case <-w.done:
            return
        case <-t.C:
            w.tick()
        }
    }
}

func (w *Worker) Close() {
    close(w.done)
}

Key invariants:

• done is closed exactly once. close(w.done) is the signal; receivers see a zero value with ok=false.
• The goroutine returns after observing the close. No further ticks are processed.
• t.Stop() runs on the way out.

The "Confirm Exit" Variant¶

A plain done channel does not tell the caller when the goroutine has finished. If you need to wait (for example, before destroying state the goroutine reads), add a wait channel that the goroutine closes on exit:

type Worker struct {
    done chan struct{}
    exit chan struct{}
}

func NewWorker() *Worker {
    w := &Worker{done: make(chan struct{}), exit: make(chan struct{})}
    go w.run()
    return w
}

func (w *Worker) run() {
    defer close(w.exit)
    t := time.NewTicker(time.Second)
    defer t.Stop()
    for {
        select {
        case <-w.done:
            return
        case <-t.C:
            w.tick()
        }
    }
}

func (w *Worker) Close() {
    close(w.done)
    <-w.exit // wait for run() to return
}

Close is now synchronous. When it returns, the goroutine is gone and t.Stop() has run.

Idempotent Close¶

Closing an already-closed channel panics. If Close may be called more than once, guard it:

type Worker struct {
    done   chan struct{}
    exit   chan struct{}
    once   sync.Once
}

func (w *Worker) Close() {
    w.once.Do(func() {
        close(w.done)
        <-w.exit
    })
}

sync.Once makes Close safe to call any number of times.

Cancelling Through a Method Versus a Channel¶

A close-only channel is the lightest signal. A method that wraps the close is more Go-idiomatic and allows future additions (logging, metrics, drain). Prefer the method form for any exported API; reserve the bare channel for tightly-scoped internal use.

Combining Ticker with context.Context¶

The modern, recommended pattern is context.Context. It composes with HTTP request handlers, gRPC, errgroup, and every other cancellation-aware part of the standard library.

The Basic Shape¶

func Loop(ctx context.Context) error {
    t := time.NewTicker(500 * time.Millisecond)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        case <-t.C:
            if err := doWork(ctx); err != nil {
                return err
            }
        }
    }
}

Notes:

• ctx.Err() returns either context.Canceled or context.DeadlineExceeded. Returning it lets the caller distinguish causes.
• doWork(ctx) takes the context so it too can exit early.
• The loop's responsibility is cancellation responsiveness, not deciding whether the error is fatal. The caller decides.

Inheriting Cancellation Trees¶

func Service(parentCtx context.Context) error {
    ctx, cancel := context.WithCancel(parentCtx)
    defer cancel()

    g, ctx := errgroup.WithContext(ctx)
    g.Go(func() error { return Loop(ctx) })
    g.Go(func() error { return Consumer(ctx) })
    return g.Wait()
}

When parentCtx is cancelled, both Loop and Consumer exit. If either returns an error, errgroup cancels ctx and the other follows. Structured concurrency, plus tickers, plus cancellation.

Timeouts Inside the Handler¶

A handler that may itself be slow should respect a timeout:

case <-t.C:
    cctx, cancel := context.WithTimeout(ctx, 200*time.Millisecond)
    err := doWork(cctx)
    cancel()
    if err != nil {
        log.Printf("work failed: %v", err)
    }
}

context.WithTimeout allocates and cancel is deferred-less here for tightness — the explicit cancel() runs immediately after doWork returns. The timeout protects against a slow downstream stalling the loop.

If you forget the cancel, the cleanup goroutine for the timeout context leaks until the deadline elapses. Always pair WithTimeout with cancel.

Why context Beats a Plain Done Channel¶

• Universal — every Go function that accepts a context.Context integrates with no glue.
• Carries deadlines, not just cancellation. A timeout in Loop propagates naturally.
• Avoids the panic-on-double-close hazard.
• Pairs with errgroup and select naturally.
• Carries request-scoped values (logger, trace span) for free.

The downside is a small allocation per WithCancel/WithTimeout. For a long-lived service this is irrelevant; for a microsecond-budget hot path it can matter, but you would not be using a ticker there anyway.

Anti-Pattern: Storing context in a Struct¶

type Worker struct {
    ctx context.Context // do not do this
}

context.Context is meant to be passed as a parameter, not stored. Storing it makes the goroutine's lifetime opaque and ties the struct to one context instance. Prefer:

type Worker struct {
    cancel context.CancelFunc
    done   chan struct{}
}

Take parentCtx as a parameter to Start(parentCtx), derive a child context with context.WithCancel, store the cancel, and use it from Stop.

Dynamic Intervals at Runtime¶

Many real systems want the ticker period to adapt: faster when there is work, slower when idle; faster after a failure, slower after success; faster during a maintenance window, slower otherwise.

Adaptive Polling¶

A typical polling loop:

func Poll(ctx context.Context) error {
    const (
        minPeriod = 100 * time.Millisecond
        maxPeriod = 10 * time.Second
    )
    period := minPeriod
    t := time.NewTicker(period)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        case <-t.C:
            n, err := pollOnce(ctx)
            if err != nil {
                return err
            }
            switch {
            case n > 0 && period > minPeriod:
                period /= 2
                if period < minPeriod {
                    period = minPeriod
                }
                t.Reset(period)
            case n == 0 && period < maxPeriod:
                period *= 2
                if period > maxPeriod {
                    period = maxPeriod
                }
                t.Reset(period)
            }
        }
    }
}

Behaviour:

• Starts fast (100ms).
• Doubles the period each time pollOnce returns zero items.
• Halves the period each time pollOnce returns at least one item.
• Caps at 10s on the slow end, floors at 100ms on the fast end.

This is exponential backoff in the slow direction and additive speedup (well, halving — geometric) in the fast direction. It is a reasonable default for queue consumers, change detectors, and similar "poll until something happens" loops.

Reset Versus Recreate¶

The example above uses Reset. It would work just as well with Stop + NewTicker:

t.Stop()
t = time.NewTicker(period)

Two differences:

1. Reset keeps t.C stable; references to it from outside the loop remain valid. Recreating swaps t.C.
2. Reset is allocation-free; recreating allocates a fresh runtime timer.

For a loop that may change interval many times, prefer Reset. For a one-shot reconfiguration on a config-reload event, either works.

Hysteresis to Avoid Thrashing¶

Adaptive intervals can oscillate if the input is on the boundary of "items present." Add hysteresis so the period changes only after sustained signal:

emptyStreak := 0
busyStreak := 0
// ...
if n > 0 {
    busyStreak++
    emptyStreak = 0
    if busyStreak >= 3 && period > minPeriod {
        period /= 2
        if period < minPeriod {
            period = minPeriod
        }
        t.Reset(period)
        busyStreak = 0
    }
} else {
    emptyStreak++
    busyStreak = 0
    if emptyStreak >= 5 && period < maxPeriod {
        period *= 2
        if period > maxPeriod {
            period = maxPeriod
        }
        t.Reset(period)
        emptyStreak = 0
    }
}

Three consecutive "busy" iterations to speed up, five consecutive "empty" iterations to slow down. The asymmetric thresholds give a small bias toward staying fast under bursty load.

Bounded Exponential Backoff¶

A common pattern for retry loops:

func RetryWithTicker(ctx context.Context, do func(ctx context.Context) error) error {
    const (
        initial = 100 * time.Millisecond
        max     = 30 * time.Second
    )
    period := initial
    t := time.NewTicker(period)
    defer t.Stop()
    for {
        err := do(ctx)
        if err == nil {
            return nil
        }
        select {
        case <-ctx.Done():
            return ctx.Err()
        case <-t.C:
        }
        period = period * 2
        if period > max {
            period = max
        }
        t.Reset(period)
    }
}

Note: this uses the ticker as a delay generator, not a steady tick. Each successful retry resets the ticker for the new period. The pattern is debatable — a one-shot time.NewTimer with Reset would be more correct semantically, since each iteration is a single delay, not a recurring interval. The ticker form is shown because it is what many code bases actually use; in a senior review you would likely refactor to a Timer.

Coalescing Rapidly-Changing Intervals¶

If your control code changes the interval many times per second, the ticker can be falling all over itself. Coalesce changes with a debounced applier:

type IntervalSetter struct {
    next   atomic.Int64 // time.Duration as int64
    apply  chan struct{}
}

func (s *IntervalSetter) Set(d time.Duration) {
    s.next.Store(int64(d))
    select {
    case s.apply <- struct{}{}:
    default:
    }
}

func (s *IntervalSetter) Run(ctx context.Context, t *time.Ticker) {
    for {
        select {
        case <-ctx.Done():
            return
        case <-s.apply:
            d := time.Duration(s.next.Load())
            if d > 0 {
                t.Reset(d)
            }
        }
    }
}

The control side calls Set(d) freely; the applier reads the latest stored value when it gets a chance. The ticker sees at most one Reset per applier iteration.

Bounds Checking the User-Supplied Interval¶

Always sanity-check intervals before passing them to Reset:

func sanitize(d time.Duration) time.Duration {
    const (
        floor = time.Millisecond
        ceil  = 24 * time.Hour
    )
    if d < floor {
        return floor
    }
    if d > ceil {
        return ceil
    }
    return d
}

t.Reset(sanitize(userSupplied))

A user-supplied "0" panics; a "negative" panics; a "year" likely indicates a bug. Define and enforce a tolerance window.

Stop on Exit: The Discipline¶

Stop is mandatory, full stop. The middle-level rules:

1. Call Stop exactly once per NewTicker.
2. Call it before the surrounding goroutine returns, so the runtime can release the timer slot.
3. Use defer immediately after NewTicker. Refactoring the loop should not break the dispose.
4. If the ticker is stored in a struct, the struct's Close/Shutdown method must call Stop.
5. If the ticker is owned by a context-derived loop, defer Stop() at the top of the loop function.

What Stop Does (And Does Not)¶

Stop removes the timer entry from the runtime heap. After Stop:

• No further values will be sent to t.C.
• t.C is not closed. Receivers waiting on it will block forever.
• One value may still be observable on t.C if the runtime had already sent before Stop won the race.

The non-closed channel surprises people. Stop mirrors "stop firing"; it does not mirror "close the channel and signal end of stream." The closure must come from the consumer side (the loop exiting on ctx.Done()).

Forgetting Stop¶

func Heartbeat() {
    t := time.NewTicker(time.Second) // never stopped
    for now := range t.C {
        send(now)
    }
}

Heartbeat never returns. The ticker entry stays in the runtime heap forever. Every minute that passes, the runtime wakes the goroutine to send into t.C. The goroutine runs send and loops. No leak yet — until the surrounding component is supposed to be disposed and the caller has no way to make Heartbeat exit.

This is the classic "fire and forget" leak. The fix is one of:

• Pass a context. Exit on cancel. defer t.Stop().
• Have the function take a done channel and break out.
• Make the function a method of a struct that has a Close method.

Verifying Stop Happens¶

In tests, wrap the function under test with goleak.VerifyNone(t):

func TestHeartbeat_NoLeak(t *testing.T) {
    defer goleak.VerifyNone(t)
    ctx, cancel := context.WithCancel(context.Background())
    cancel()
    Heartbeat(ctx)
}

goleak (from go.uber.org/goleak) snapshots the goroutine list before and after the test. A leak fails the test. Add it to ticker-related tests at minimum.

Production Verification¶

In production, expose runtime.NumGoroutine() as a metric. A creeping goroutine count over hours or days is the canonical leak signature. Pair it with /debug/pprof/goroutine?debug=2: if you see hundreds of stacks blocked at time.Sleep or in a ticker loop, that is your leak.

Idempotency¶

Stop may be called any number of times. Subsequent calls are no-ops. The first call returns true if it actually removed the timer (i.e. a tick was not yet in flight), false otherwise. The return value is informational — most code ignores it for Ticker (it matters more for Timer).

Stop Inside the Loop¶

Calling Stop inside the loop, then continuing, leaves t.C empty forever. The loop will block on receive — unless you have other cases in the select. If you do have other cases, the loop functions as "ticker disabled," which is a defensible state.

for {
    select {
    case <-ctx.Done():
        return
    case <-t.C:
        if shouldDisable() {
            t.Stop()
            // future iterations select on ctx.Done() and any other cases
        } else {
            doWork()
        }
    case msg := <-otherChan:
        handle(msg)
    }
}

To re-enable, t.Reset(period).

Stop in a Defer Cascade¶

If the surrounding goroutine has multiple deferred cleanups, the order matters:

defer wg.Done()        // signal "I'm done" last
defer t.Stop()         // stop ticker first
defer close(out)       // close output channel

Defers run in reverse order: close(out) runs first, then t.Stop(), then wg.Done(). That is correct — the work is "close the output, then release the ticker, then signal the waiter." If you have a logger that should record exit, defer the log line very last (so it runs first).

Slow Consumers and Dropped Ticks¶

Ticker.C is a buffered channel of capacity 1. (Internally, the runtime's send is non-blocking; if the buffer is full, the value is discarded.) The consequence: if the consumer takes longer than the period, ticks are dropped, not queued.

A Demonstration¶

t := time.NewTicker(100 * time.Millisecond)
defer t.Stop()

for i := 0; i < 5; i++ {
    now := <-t.C
    fmt.Println(i, now)
    time.Sleep(350 * time.Millisecond) // slower than period
}

Output (timestamps abbreviated):

0 t=0.1
1 t=0.45  // not t=0.2 — that tick was dropped
2 t=0.8
3 t=1.15
4 t=1.5

Between each iteration, the runtime tried to send ticks at the 200ms, 300ms, and 400ms marks — but the consumer was busy. The buffer absorbed at most one; the rest were dropped silently.

Why Drop Rather Than Queue¶

If the runtime queued every missed tick, a slow consumer would see an avalanche of "stale" ticks when it caught up. That is rarely useful: the work attached to a tick is usually "do this thing now," and doing it twice in rapid succession is worse than doing it once.

Dropping also bounds memory: a stalled consumer cannot grow t.C without bound.

The trade-off: the consumer cannot observe how many ticks it missed without measuring elapsed time. If you need that signal, record the wall-clock time of each tick and compare against the expected sequence.

Detecting Drops¶

A simple wrapper that surfaces drops:

type CountingTicker struct {
    t       *time.Ticker
    period  time.Duration
    last    time.Time
    Dropped atomic.Int64
}

func NewCountingTicker(d time.Duration) *CountingTicker {
    return &CountingTicker{t: time.NewTicker(d), period: d}
}

func (c *CountingTicker) Recv() time.Time {
    now := <-c.t.C
    if !c.last.IsZero() {
        gap := now.Sub(c.last)
        missed := int64(gap/c.period) - 1
        if missed > 0 {
            c.Dropped.Add(missed)
        }
    }
    c.last = now
    return now
}

func (c *CountingTicker) Stop() { c.t.Stop() }

Dropped.Load() shows how many ticks the consumer missed since start. Useful as a metric to alert on slow consumers.

Handling Drops¶

Three options when ticks are dropped:

1. Ignore the drops. Fine for idempotent periodic work — "flush the cache every 5s" tolerates running every 5s±N.
2. Compensate per drop. "Send N heartbeats" — if you missed 3, send 3. Achievable only if you record what was missed; harder than it sounds.
3. Apply backpressure. Slow the producer side. Easier said than done with a ticker: you cannot slow the runtime down. Practical alternative: switch to a self-clocked loop that ticks again after each completion (see below).

The Self-Clocked Loop¶

If you cannot tolerate drops, drive the cadence from the work itself:

func Loop(ctx context.Context, period time.Duration) {
    for {
        if err := ctx.Err(); err != nil {
            return
        }
        start := time.Now()
        doWork(ctx)
        elapsed := time.Since(start)
        if elapsed < period {
            select {
            case <-ctx.Done():
                return
            case <-time.After(period - elapsed):
            }
        }
    }
}

This guarantees no drops because the next tick is scheduled relative to the previous completion. The downside is that long work shifts the schedule (drift), unlike a ticker which holds the schedule. Choose based on whether drift or drops is the bigger sin.

Note: time.After is used here only because the loop body owns the wait — there is no goroutine that survives between iterations, so the per-iteration timer allocation is correct. The earlier rule "no time.After in a loop" applies when the timer is in a select alongside other long-lived cases.

Jittered Tickers¶

When many processes start at the same time (a deploy, a cron-spawned batch), their tickers can synchronise. Every process ticks at the same wall-clock instants, hammering shared infrastructure (DBs, external APIs) in waves. This is the thundering herd.

Adding Jitter¶

Two strategies.

Random initial offset. Each instance sleeps a random fraction of the period before constructing the ticker:

func StartHeartbeat(ctx context.Context, period time.Duration) {
    offset := time.Duration(rand.Int63n(int64(period)))
    select {
    case <-ctx.Done():
        return
    case <-time.After(offset):
    }
    t := time.NewTicker(period)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            return
        case <-t.C:
            heartbeat()
        }
    }
}

After the initial offset, the periods are still synchronised (every instance ticks at the same relative cadence) — but the phases differ. Load to the downstream is now spread across the period.

Per-tick jitter. Each tick adds a small random delay before doing work:

for {
    select {
    case <-ctx.Done():
        return
    case <-t.C:
        time.Sleep(time.Duration(rand.Int63n(int64(period / 10))))
        doWork()
    }
}

The Sleep smears the work over a window. Useful when the work itself is the load (e.g. polling an HTTP API) and the runtime tick is not.

The Jittered Sleep, in Detail¶

The constant period / 10 is a stylistic choice — 10% of the period. The right value depends on:

• How many instances are running. More instances need more jitter.
• How much of the period your work uses. If work takes 80% of the period, you only have 20% to jitter into.
• How synchronised the start times are. Many cron-launched instances need more.

A reasonable default: jitter the start by a uniform [0, period), then run a steady ticker.

Cryptographically Safe Random Is Not Needed¶

math/rand is fine for jitter. You do not need crypto/rand. The point is decorrelation across instances, not unpredictability against an adversary.

Seed once at program start:

func init() {
    rand.Seed(time.Now().UnixNano())
}

On Go 1.20+ the global random source is auto-seeded; you can drop the explicit seed.

Decorrelated Jitter¶

For backoff loops, "decorrelated jitter" (a Resilience4j / AWS architecture pattern) avoids synchronisation across retries:

func decorrelated(prev, base, cap time.Duration) time.Duration {
    next := base + time.Duration(rand.Int63n(int64(3*prev)))
    if next > cap {
        next = cap
    }
    return next
}

Each retry's delay is sampled from [base, 3 * prev]. Convergence is similar to exponential backoff but with built-in dispersion.

Jittering Many Tickers at Once¶

If a single service starts dozens of tickers (one per resource, say), and they all use the same period, jitter each independently:

for _, r := range resources {
    go startTicker(r, period, time.Duration(rand.Int63n(int64(period))))
}

The per-ticker offsets are independent random samples, so the tickers fan out across the period.

Drift-Corrected Loops¶

A Ticker already corrects drift internally — it schedules each fire relative to the previous intended time. So when you say "drift-corrected loop," you usually mean one of:

1. A loop that uses time.Sleep instead of a ticker and needs explicit drift correction.
2. A loop that does drifting work between ticks and wants to compensate.
3. A loop that synthesises its own schedule (e.g. "fire at t=0, t=π, t=2π, ...").

The Sleep-Based Loop With Drift Correction¶

func DriftCorrectedLoop(ctx context.Context, period time.Duration, fn func()) {
    next := time.Now().Add(period)
    for {
        wait := time.Until(next)
        if wait < 0 {
            wait = 0
        }
        select {
        case <-ctx.Done():
            return
        case <-time.After(wait):
        }
        fn()
        next = next.Add(period)
    }
}

next advances by exactly period each iteration regardless of how long fn took. If fn ran over budget, wait becomes negative; the loop fires immediately, "catching up." Over many iterations, the mean fire rate matches the period.

This is conceptually equivalent to what a Ticker does internally, but in user code. The tradeoff: more allocations (time.After per iteration), more complexity, but greater control over the schedule.

Catch-Up Behaviour¶

If fn takes 3 periods, the next three iterations of the loop fire back-to-back to catch up. That can cause cascading load. To bound catch-up:

next = next.Add(period)
if next.Before(time.Now()) {
    next = time.Now().Add(period) // re-baseline, drop the missed beats
}

Now the loop skips dropped beats rather than burst-firing. This is the same trade-off a Ticker makes by default.

Phase-Locked Loops¶

For loops that must align with an external clock (e.g. "fire at the next round second"):

func PhaseLocked(ctx context.Context, fn func()) {
    for {
        now := time.Now()
        next := now.Truncate(time.Second).Add(time.Second)
        wait := next.Sub(now)
        select {
        case <-ctx.Done():
            return
        case <-time.After(wait):
        }
        fn()
    }
}

Each iteration computes the next round-second boundary and waits for it. Drift is corrected because the schedule is re-derived every iteration from time.Now(). The downside is sensitivity to wall-clock jumps.

A safer hybrid uses a ticker for cadence and time.Until for alignment within a tolerance — but it gets complicated quickly.

Ticker Versus time.After in a Loop¶

The reason a separate Ticker exists, despite time.After being a one-liner:

for {
    select {
    case <-ctx.Done():
        return
    case <-time.After(time.Second):
        doWork()
    }
}

This looks innocuous. It is not. Three problems.

Problem 1: Allocation Per Iteration¶

time.After(d) allocates a time.Timer every call. In a tight loop that fires often, the GC pressure adds up. Profilers regularly show time.After near the top of allocation-heavy services.

Problem 2: Pre-Go-1.23 Timer Leakage¶

Before Go 1.23, a timer constructed by time.After is not garbage collected until it fires. If ctx.Done() triggers and the loop exits, any in-flight timers continue to occupy heap slots until their scheduled fire time. For a 1-second period, that's no big deal. For a 1-hour period in a fast-cancelling system, you can accumulate thousands of unfireable timers.

Go 1.23 changed this: timers without active references are eligible for GC even before firing. But your code may run on older Go versions. The defensive default is: do not use time.After inside a loop where the loop might exit before the timer fires.

Problem 3: Race on First Iteration¶

time.After(d) is scheduled the moment the select evaluates its cases. If the context is already cancelled, the timer is still scheduled — and lives until it fires. On a cancel-then-call sequence, you can leak a timer per call.

The Fix: One Long-Lived Ticker¶

t := time.NewTicker(time.Second)
defer t.Stop()
for {
    select {
    case <-ctx.Done():
        return
    case <-t.C:
        doWork()
    }
}

• One allocation, at construction.
• defer t.Stop() releases the heap entry on exit, regardless of pending ticks.
• No per-iteration GC pressure.
• Same readability.

When time.After Is Fine¶

In a non-loop context: a single delay, then continue. time.After is the right tool:

select {
case <-ctx.Done():
case <-time.After(time.Second):
}

In a loop where the period is truly variable per iteration and changing it via Reset would be awkward: e.g. an exponential-backoff retry loop where each iteration is a one-shot delay, not a recurring tick. Even there, time.NewTimer with Reset is more efficient than time.After. The senior file discusses this in depth.

Summary Table¶

Ticker Versus time.AfterFunc¶

time.AfterFunc(d, fn) runs fn in a fresh goroutine after d. It is not a ticker — it fires once — but it overlaps in design space.

When AfterFunc Is Better Than Ticker¶

• The work is small and you have many independent schedules. AfterFunc does not require a goroutine to host a select loop; the runtime's timer thread runs fn directly.
• You only need a delay before some one-shot action.
• You want to schedule something for "after I'm done with this scope" without holding open a goroutine.

When Ticker Is Better Than AfterFunc¶

• The work recurs at a steady cadence.
• You need to coordinate with other channels (cancellation, input). Ticker integrates with select; AfterFunc does not.
• You need to mutate the schedule (Reset). Both support it, but with different ergonomics.
• You want to observe missed fires. Ticker drops silently to t.C; AfterFunc does not have a buffered surface.

A Recurring AfterFunc¶

You can build a recurring schedule from AfterFunc by having fn re-schedule itself:

type Recurring struct {
    mu     sync.Mutex
    fn     func()
    period time.Duration
    timer  *time.Timer
    done   bool
}

func NewRecurring(period time.Duration, fn func()) *Recurring {
    r := &Recurring{fn: fn, period: period}
    r.timer = time.AfterFunc(period, r.tick)
    return r
}

func (r *Recurring) tick() {
    r.mu.Lock()
    done := r.done
    r.mu.Unlock()
    if done {
        return
    }
    r.fn()
    r.mu.Lock()
    if !r.done {
        r.timer.Reset(r.period)
    }
    r.mu.Unlock()
}

func (r *Recurring) Stop() {
    r.mu.Lock()
    r.done = true
    r.timer.Stop()
    r.mu.Unlock()
}

That's a poor cousin of NewTicker. Use NewTicker for recurring schedules unless you have a specific reason not to.

Concurrency Note on AfterFunc¶

The callback in AfterFunc runs in its own goroutine. Multiple AfterFunc callbacks can run concurrently. If your fn is not safe to call concurrently with itself or with other code, you need explicit synchronisation. With Ticker, the consumer loop serialises calls; with AfterFunc, you do not get that for free.

Testability: Mocking and Fake Clocks¶

Real-time ticker tests are slow and flaky. A test that waits for a 500ms tick takes at least 500ms, and on a CI machine under load may take seconds. Test pyramids hate this. The fix is a fake clock: a clock interface that test code can advance manually.

The Clock Interface¶

Define a narrow interface for the time operations your code uses:

type Clock interface {
    Now() time.Time
    NewTicker(d time.Duration) Ticker
}

type Ticker interface {
    Chan() <-chan time.Time
    Reset(d time.Duration)
    Stop()
}

The real implementation wraps time.NewTicker:

type realClock struct{}

func (realClock) Now() time.Time { return time.Now() }

func (realClock) NewTicker(d time.Duration) Ticker {
    t := time.NewTicker(d)
    return &realTicker{t: t}
}

type realTicker struct {
    t *time.Ticker
}

func (r *realTicker) Chan() <-chan time.Time { return r.t.C }
func (r *realTicker) Reset(d time.Duration)  { r.t.Reset(d) }
func (r *realTicker) Stop()                   { r.t.Stop() }

The Fake Clock¶

type fakeClock struct {
    mu      sync.Mutex
    now     time.Time
    tickers []*fakeTicker
}

func newFakeClock(start time.Time) *fakeClock {
    return &fakeClock{now: start}
}

func (c *fakeClock) Now() time.Time {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.now
}

func (c *fakeClock) NewTicker(d time.Duration) Ticker {
    c.mu.Lock()
    defer c.mu.Unlock()
    t := &fakeTicker{
        c:      make(chan time.Time, 1),
        period: d,
        next:   c.now.Add(d),
    }
    c.tickers = append(c.tickers, t)
    return t
}

func (c *fakeClock) Advance(d time.Duration) {
    c.mu.Lock()
    target := c.now.Add(d)
    c.mu.Unlock()
    for {
        c.mu.Lock()
        next := target
        var fire *fakeTicker
        for _, t := range c.tickers {
            if !t.stopped && !t.next.After(target) && (fire == nil || t.next.Before(fire.next)) {
                next = t.next
                fire = t
            }
        }
        if fire == nil {
            c.now = target
            c.mu.Unlock()
            return
        }
        c.now = next
        fire.next = fire.next.Add(fire.period)
        ch := fire.c
        firingTime := c.now
        c.mu.Unlock()
        select {
        case ch <- firingTime:
        default:
        }
    }
}

type fakeTicker struct {
    c       chan time.Time
    period  time.Duration
    next    time.Time
    stopped bool
}

func (t *fakeTicker) Chan() <-chan time.Time { return t.c }
func (t *fakeTicker) Reset(d time.Duration)  { t.period = d }
func (t *fakeTicker) Stop()                  { t.stopped = true }

The fake clock advances by manual call. Each Advance walks the registered tickers in order, firing each that is due, in monotonic order, with the per-tick "now" set correctly.

Using It in a Test¶

func TestLoop(t *testing.T) {
    clk := newFakeClock(time.Unix(0, 0))
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    counts := make(chan int, 10)
    go Loop(ctx, clk, 100*time.Millisecond, func() { counts <- 1 })

    clk.Advance(550 * time.Millisecond)
    cancel()

    total := 0
    for {
        select {
        case <-counts:
            total++
        default:
            // drain
            goto done
        }
    }
done:
    if total != 5 {
        t.Fatalf("expected 5 ticks, got %d", total)
    }
}

The test runs in microseconds and the result is deterministic.

Existing Libraries¶

You do not have to write a fake clock yourself. Battle-tested options:

• github.com/benbjohnson/clock — the de facto standard, includes Mock with full After, AfterFunc, Ticker, Timer support.
• github.com/jonboulle/clockwork — alternative with similar surface.
• The standard library testing/synctest (Go 1.24+, experimental in 1.23) lets you write tests against the real time package with fast simulated time. Worth watching but not yet default.

For new code, depend on benbjohnson/clock; it gives you nine-tenths of what you need without inventing your own abstraction.

Avoiding the Clock Abstraction¶

Not every codebase needs a clock abstraction. If your ticker tests can tolerate real time and short periods (millisecond-scale), and the test count is small, plain time.NewTicker is fine. The threshold to introduce the abstraction is:

• More than a handful of time-dependent tests, OR
• Need to simulate hours or days of elapsed time, OR
• Flaky tests due to CI scheduling jitter.

Hit any of those, switch to a fake clock.

Bridging Real Time and Fake Time in One Codebase¶

A common evolution: a project starts with time.NewTicker everywhere, gains too many slow tests, decides to refactor. The migration looks like a series of small steps:

1. Add a Clock interface and a default real implementation.
2. Inject the clock where the new tests need it.
3. Leave old code paths on real time until they need testing.
4. Eventually, run a gopls rename to push the interface everywhere.

Avoid the temptation to "do it once, properly" across a large code base. The smaller migration is faster, less risky, and lands the value where it pays off first.

The Synctest Experiment¶

Go 1.24's testing/synctest package (currently a synctest_internal flag in 1.23) takes a different approach: simulate time within a goroutine bubble. Code inside synctest.Run sees a virtual time that advances when all goroutines are blocked. The standard time.NewTicker works inside the bubble, with the bubble's clock.

func TestLoop_Synctest(t *testing.T) {
    synctest.Run(func() {
        ctx, cancel := context.WithCancel(context.Background())
        defer cancel()
        ch := make(chan time.Time, 10)
        go func() {
            t := time.NewTicker(time.Second)
            defer t.Stop()
            for {
                select {
                case <-ctx.Done():
                    return
                case now := <-t.C:
                    ch <- now
                }
            }
        }()
        time.Sleep(3500 * time.Millisecond)
        cancel()
        close(ch)
        var ticks []time.Time
        for v := range ch {
            ticks = append(ticks, v)
        }
        if len(ticks) != 3 {
            t.Fatalf("expected 3 ticks, got %d", len(ticks))
        }
    })
}

When this stabilises in Go 1.24+, the manual Clock abstraction becomes mostly unnecessary. For now, stay with benbjohnson/clock for production code.

Patterns from Production Codebases¶

The following patterns appear in many large Go services. Treat them as building blocks; each composes with the others.

Pattern 1: Heartbeat Goroutine¶

A service publishes liveness on a fixed cadence. The heartbeat goroutine is its own component:

type Heartbeat struct {
    period time.Duration
    send   func(context.Context, time.Time) error
    cancel context.CancelFunc
    done   chan error
}

func NewHeartbeat(period time.Duration, send func(context.Context, time.Time) error) *Heartbeat {
    return &Heartbeat{period: period, send: send}
}

func (h *Heartbeat) Start(parent context.Context) {
    ctx, cancel := context.WithCancel(parent)
    h.cancel = cancel
    h.done = make(chan error, 1)
    go h.run(ctx)
}

func (h *Heartbeat) Stop() error {
    if h.cancel == nil {
        return nil
    }
    h.cancel()
    return <-h.done
}

func (h *Heartbeat) run(ctx context.Context) {
    var err error
    defer func() { h.done <- err }()
    t := time.NewTicker(h.period)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            err = ctx.Err()
            return
        case now := <-t.C:
            if e := h.send(ctx, now); e != nil {
                err = e
                return
            }
        }
    }
}