Timer Leaks — Middle Level¶

Table of Contents¶

1. Introduction
2. The Five Timer APIs in One Picture
3. NewTimer and the Stop Pattern
4. The Reset Gotcha
5. Re-Use vs Re-Allocate: Building a Hot-Path Timer
6. The select { case <-time.After(d) } Loop Leak
7. The Phantom "default Saved Me" Myth
8. AfterFunc and Stop Race Conditions
9. Ticker Leaks and Misuse of time.Tick
10. Per-Connection Deadlines vs Timers
11. Testing Timer-Heavy Code
12. Detection Cheatsheet
13. Refactor Walkthroughs
14. Self-Assessment
15. Summary

Introduction¶

At the junior level you learned the headline: time.After allocates a *time.Timer every call, drops the reference, and the runtime keeps the timer body alive until it fires. Inside a hot loop where the timer rarely wins, that is a textbook leak. The fix is a single reusable *time.Timer whose Stop and Reset you manage by hand.

That is the slogan. The middle-level question is how to actually live with that slogan in a real codebase. Real services do not look like the textbook example. They have:

• A select with three or four channels, only one of which is the timeout.
• A timer reused across iterations but only sometimes — there is a fast path that takes a case <-ch and exits before the timer would ever start.
• A Reset called on a timer that may or may not have fired, depending on a race the author never thought about.
• A time.AfterFunc callback that holds a pointer to a request that the caller already returned.
• A goroutine that subscribes to a time.Tick and then crashes — the Ticker keeps firing into nothing for the lifetime of the process.

This page walks through each of those situations, shows the code you will inherit, the bug as it actually appears in pprof, and the rewrite. We close with detection commands you can run today on a service you already operate.

After reading this you will:

• Read and write NewTimer + Stop + Reset patterns confidently, including the drain step.
• Know exactly when Reset is safe and when it requires a Stop first.
• Spot a time.After inside a for { select { ... } } loop in code review without reading the surrounding code.
• Understand why adding default: to a select does not save you from the time.After leak.
• Make Ticker cleanup as reliable as defer file.Close().
• Use pprof heap snapshots, runtime.MemStats, and goleak to confirm a timer leak is fixed.

The Five Timer APIs in One Picture¶

The time package exposes five timer-related entry points that all share the same underlying runtime timer machinery. Knowing which one you are using — and which channel you are reading from — is half the battle.

Three things to note up front:

1. time.After(d) is essentially time.NewTimer(d).C. The *Timer itself is dropped on the floor. You cannot stop it.
2. time.Tick(d) is similarly time.NewTicker(d).C. The *Ticker is dropped. You cannot stop it. The runtime keeps it alive for the lifetime of the process. The standard library godoc literally says "Tick is a convenience wrapper for NewTicker providing access to the ticking channel only. Unlike NewTicker, Tick will return nil if d <= 0. While Tick is useful for clients that have no need to shut down the Ticker, be aware that without a way to shut it down the underlying Ticker cannot be recovered by the garbage collector; it 'leaks'." That last sentence is in the docs.
3. time.AfterFunc does not use a channel. The callback f runs on its own goroutine. This means stopping it is not the same as draining a channel.

If you remember nothing else, remember: time.After and time.Tick are "leaky by default, fine in throwaway code, dangerous in long-running code." The other three are stoppable, but stopping them correctly requires understanding the Stop/Reset rules below.

The runtime-level picture¶

All five APIs end up in the runtime's internal timer machinery. Every *time.Timer (and every internal timer behind time.Tick, time.After, time.AfterFunc) corresponds to a runtime.timer struct that lives inside a per-P timer heap. When you call Stop, the runtime removes the entry from that heap. When you do not call Stop, the entry stays in the heap until the timer fires.

This is the core of "timer leak": every active entry in the runtime timer heap pins memory.

• Pre-Go 1.23, that memory was the entire *time.Timer value, including any associated channel buffer.
• In Go 1.23+, the runtime was reworked so an unreferenced timer can be collected by the garbage collector even before its fire time. This dramatically reduces the cost of time.After in loops — but it does not eliminate it, and you should still not rely on it.

The senior-level page goes into this internals topic in detail. At middle level, treat the heap as a black box that fills up with whatever you forget to stop.

NewTimer and the Stop Pattern¶

time.NewTimer(d) returns a *time.Timer. You receive on t.C. You stop it with t.Stop(). That is the entire surface — but each step has rules.

The minimum viable usage¶

package main

import (
    "fmt"
    "time"
)

func main() {
    t := time.NewTimer(100 * time.Millisecond)
    defer t.Stop()

    select {
    case fired := <-t.C:
        fmt.Println("fired at:", fired)
    }
}

This program compiles, runs, prints, and exits. The defer t.Stop() is harmless if the timer already fired (it returns false) and useful if we exit the function before the timer would have fired.

The Stop return value¶

stopped := t.Stop()

• stopped == true means the timer was active at the moment of the call, the runtime took it out of the heap, and the channel has not received its value (and will not, unless you Reset).
• stopped == false means one of two things:
• The timer already fired (its value is now sitting in t.C, waiting for a reader).
• The timer was already stopped earlier.

That second meaning of false is the one that trips people up. It is not an error condition. It is information you need before you decide whether to drain the channel.

When you must drain the channel¶

If you intend to call Reset and Stop returned false, the channel might still have a value queued. If you Reset without draining, the next read on t.C will fire immediately with the old value. That is almost never what you want.

The textbook drain-before-reset:

if !t.Stop() {
    // The timer fired before Stop could remove it.
    // There might be a value waiting in t.C.
    select {
    case <-t.C:
    default:
    }
}
t.Reset(newDuration)

The select with default is the standard non-blocking drain. It reads one value if present, returns immediately if not.

Note: this is the drain-then-reset idiom and it is unrelated to the false default myth in the section below. Here default is correct because we genuinely want a non-blocking peek at a value-or-nothing channel.

Common shape: timeout in a worker¶

func work(in <-chan Job, timeout time.Duration) error {
    t := time.NewTimer(timeout)
    defer t.Stop()

    for {
        if !t.Stop() {
            select {
            case <-t.C:
            default:
            }
        }
        t.Reset(timeout)

        select {
        case j, ok := <-in:
            if !ok {
                return nil
            }
            if err := process(j); err != nil {
                return err
            }
        case <-t.C:
            return errTimeout
        }
    }
}

This is correct, but somewhat noisy. Every iteration is:

1. Stop the timer, possibly drain its channel.
2. Reset the timer.
3. Wait on either a job or the timer.

If you find yourself writing this pattern more than twice, extract it into a helper.

A helper for resetting¶

// resetTimer cancels t and resets it to d, draining the channel if necessary.
// It is safe to call regardless of the timer's current state, as long as
// no other goroutine is racing on the same timer.
func resetTimer(t *time.Timer, d time.Duration) {
    if !t.Stop() {
        select {
        case <-t.C:
        default:
        }
    }
    t.Reset(d)
}

Now the worker is:

func work(in <-chan Job, timeout time.Duration) error {
    t := time.NewTimer(timeout)
    defer t.Stop()

    for {
        resetTimer(t, timeout)
        select {
        case j, ok := <-in:
            if !ok {
                return nil
            }
            if err := process(j); err != nil {
                return err
            }
        case <-t.C:
            return errTimeout
        }
    }
}

The deferred Stop¶

Every NewTimer should have a defer t.Stop(). Even if you Stop inside the loop, the defer catches the early-exit cases:

t := time.NewTimer(d)
defer t.Stop()

select {
case <-ctx.Done():
    return ctx.Err() // defer t.Stop() prevents the timer from outliving us.
case v := <-t.C:
    return v, nil
}

If you forget the defer, the ctx.Done() path leaves the timer alive in the runtime heap until it fires. Pre-Go 1.23, that pinned the timer body for d milliseconds. Multiply by a hot path and you have measurable leak.

Side note: NewTimer does not leak when t.C is read¶

If the timer fires and you read its channel, the runtime is done with it — Stop is unnecessary. The Stop matters when the timer is still pending.

t := time.NewTimer(d)
<-t.C
// No Stop needed here. The timer already fired and was removed from the heap.

But it costs nothing to add defer t.Stop() at the top, and it future-proofs the function against later changes that introduce an early return.

The Reset Gotcha¶

Reset is the most miswritten timer call in Go. The function signature looks innocuous:

func (t *Timer) Reset(d time.Duration) bool

The return value is the same as Stop: true if the timer was active, false if it had expired or been stopped. But the documentation on the safe usage of Reset is one of the most carefully worded paragraphs in the entire standard library.

The rule, as the docs state it¶

Reset should always be invoked on stopped or expired timers with drained channels. If a program has already received a value from t.C, the timer is known to have expired and the channel drained, so t.Reset can be used directly. If a program has not yet received a value from t.C, however, the timer must be stopped and—if Stop reports that the timer expired before being stopped—the channel explicitly drained.

In plain English, before you call Reset you must be in one of two states:

1. You already read from t.C. The channel is drained. Reset is safe.
2. You called Stop() and drained the channel if Stop returned false. The channel is drained. Reset is safe.

If you call Reset while the timer might still fire, you have created a race: the old fire and the new fire can both end up queued in t.C, and your select will see two firings instead of one.

A wrong Reset (race scenario)¶

t := time.NewTimer(10 * time.Millisecond)

for i := 0; i < 5; i++ {
    select {
    case <-t.C:
        // Got a tick.
    case <-doSomething():
        // doSomething finished first.
    }
    t.Reset(10 * time.Millisecond) // WRONG: did not drain t.C if doSomething won.
}

If doSomething wins, t.C may still have a queued value. Reset does not remove that value. On the next iteration you might see the previous expiration immediately, even though the new 10ms have not elapsed.

A correct Reset¶

t := time.NewTimer(10 * time.Millisecond)
defer t.Stop()

for i := 0; i < 5; i++ {
    select {
    case <-t.C:
        // Got a tick. Channel is drained. Safe to Reset.
    case <-doSomething():
        // doSomething won. Channel might have a value or might not.
        if !t.Stop() {
            select {
            case <-t.C:
            default:
            }
        }
    }
    t.Reset(10 * time.Millisecond)
}

Now every path into Reset has a drained channel.

Why the original Reset was even more dangerous¶

In versions of Go before 1.23, Reset was specified to be unsafe in the presence of any concurrent goroutine. Two goroutines were allowed to call Reset and Stop on the same *Timer only if the caller could prove that the channel was drained. The runtime did its best to handle racing calls, but the user-visible state of t.C could end up with phantom values.

Go 1.23 made Reset and Stop atomic with respect to the internal channel state, so the runtime no longer races. But your user code still has to drain t.C if you do not know whether the timer fired. That is a behavior of the channel, not the timer.

A live example: connection write deadline as a timer¶

Suppose you are reimplementing a network deadline using NewTimer:

func writeWithDeadline(c net.Conn, p []byte, d time.Duration) error {
    t := time.NewTimer(d)
    defer t.Stop()

    done := make(chan error, 1)
    go func() {
        _, err := c.Write(p)
        done <- err
    }()

    select {
    case err := <-done:
        return err
    case <-t.C:
        c.Close() // Abort the write.
        return errWriteTimeout
    }
}

If done wins (write finished in time), we leave the timer pending. The defer t.Stop() cleans it up. Good.

If we also wanted to retry after the deadline, naively we might write:

for retries := 3; retries > 0; retries-- {
    select {
    case err := <-done:
        return err
    case <-t.C:
        // retry
    }
    t.Reset(d) // BUG: we did not drain if 'done' won.
}

Again, drain the channel only if necessary. The cleanest version sets the timer fresh each iteration:

for retries := 3; retries > 0; retries-- {
    t := time.NewTimer(d)
    select {
    case err := <-done:
        t.Stop()
        return err
    case <-t.C:
        // retry
    }
}

This trades one allocation per retry for clarity. For three retries that is two extra allocations. Fine.

The "always allocate" anti-pattern¶

You will see this in code reviews:

for {
    t := time.NewTimer(d)
    select {
    case <-ch:
        t.Stop()
    case <-t.C:
    }
}

This is fine if the loop runs once per second. It is a bug if the loop runs ten thousand times per second and <-ch always wins, because every iteration allocates a *time.Timer and (pre-1.23) keeps it in the heap until d elapses. The next section explores that scenario.

Re-Use vs Re-Allocate: Building a Hot-Path Timer¶

A reusable timer trades complexity (Stop + drain + Reset) for the avoidance of allocation per iteration. The trade-off matters when:

• The loop iterates fast (microsecond scale).
• The timer rarely wins (so allocating one per iteration is pure waste).
• Memory pressure is part of the SLO (latency-sensitive servers, large fanout systems).

Benchmark: per-iteration allocation vs reuse¶

package timerbench

import (
    "testing"
    "time"
)

func BenchmarkPerIterAllocate(b *testing.B) {
    ch := make(chan struct{}, 1)
    ch <- struct{}{} // pre-fill so the case wins
    for i := 0; i < b.N; i++ {
        ch <- struct{}{}
        t := time.NewTimer(time.Second)
        select {
        case <-ch:
            t.Stop()
        case <-t.C:
        }
    }
}

func BenchmarkReused(b *testing.B) {
    ch := make(chan struct{}, 1)
    t := time.NewTimer(time.Second)
    defer t.Stop()
    for i := 0; i < b.N; i++ {
        ch <- struct{}{}
        if !t.Stop() {
            select {
            case <-t.C:
            default:
            }
        }
        t.Reset(time.Second)
        select {
        case <-ch:
        case <-t.C:
        }
    }
}

On Go 1.22, the per-iteration version allocates roughly one *time.Timer per iteration plus accessory heap traffic. The reused version allocates zero per iteration after warmup. The exact numbers vary by hardware, but the gap is large enough that it shows up in production memory profiles.

What "fast path wins" means in code¶

Most timer-driven loops are timeouts: the timer is meant to fire only when something else has gone wrong. So 99.9% of iterations take the non-timer branch.

for {
    select {
    case msg := <-incoming:
        handle(msg)
    case <-time.After(idleTimeout): // bad
        cleanupAndExit()
        return
    }
}

If incoming is hot, this loop allocates a new *time.Timer for every message, even though the timer almost never fires. That is exactly the time.After-in-loop leak you read about at junior level.

The reused version:

t := time.NewTimer(idleTimeout)
defer t.Stop()

for {
    if !t.Stop() {
        select {
        case <-t.C:
        default:
        }
    }
    t.Reset(idleTimeout)
    select {
    case msg := <-incoming:
        handle(msg)
    case <-t.C:
        cleanupAndExit()
        return
    }
}

Now there is exactly one *time.Timer for the lifetime of the loop.

When not to optimise¶

If the loop runs once per second, or once per HTTP request, do not bother with the reusable pattern. The clarity of one NewTimer per iteration is worth the cheap allocation. Save the optimisation for hot paths that profile traces actually flag.

A rule of thumb: if time.After shows up in your pprof -alloc_space top list, it is time to refactor. If it does not, leave it alone.

The select { case <-time.After(d) } Loop Leak¶

This is the canonical timer leak. We covered it at junior level. At middle level we want to recognise its non-obvious variants.

Variant 1: explicit time.After¶

for {
    select {
    case msg := <-ch:
        handle(msg)
    case <-time.After(5 * time.Second):
        log.Println("idle")
    }
}

Recognisable. Fixable by replacing time.After with a reusable NewTimer.

Variant 2: a helper that returns a channel¶

Sometimes the time.After is hidden inside a helper:

func idleAfter(d time.Duration) <-chan time.Time {
    return time.After(d)
}

for {
    select {
    case msg := <-ch:
        handle(msg)
    case <-idleAfter(5 * time.Second):
        log.Println("idle")
    }
}

Same leak. The time.After call still happens once per iteration and the timer is still unreferenced.

Variant 3: chained selects¶

for {
    msg, ok := receive(ch)
    if !ok {
        return
    }
    select {
    case out <- transform(msg):
    case <-time.After(writeTimeout):
        return errWriteTimeout
    }
}

The timer is fresh each iteration even though the loop is hot. The fix uses the same Stop/Reset pattern around the inner select.

Variant 4: per-request RPC timeouts¶

func Call(ctx context.Context, req *Request) (*Response, error) {
    resp := make(chan *Response, 1)
    go func() { resp <- doRPC(req) }()

    select {
    case r := <-resp:
        return r, nil
    case <-time.After(req.Timeout):
        return nil, errTimeout
    }
}

Looks fine — Call returns after one timer. But if your service handles 50 000 RPCs per second and most return within microseconds, you allocate 50 000 timers per second and let them sit in the heap for req.Timeout. At a 30-second timeout, that is 1.5 million pending timers in the heap. Pre-1.23, that is meaningful memory.

The fix is either:

• Use context.WithTimeout, which is what context was built for. The deadline is enforced by the runtime via a single internal timer per context, not per select arm.
• Or, if you really want a manual timer, use NewTimer + Stop.

func Call(ctx context.Context, req *Request) (*Response, error) {
    ctx, cancel := context.WithTimeout(ctx, req.Timeout)
    defer cancel()

    resp := make(chan *Response, 1)
    go func() { resp <- doRPC(ctx, req) }()

    select {
    case r := <-resp:
        return r, nil
    case <-ctx.Done():
        return nil, ctx.Err()
    }
}

context.WithTimeout internally calls time.AfterFunc once and t.Stop() in cancel. You get the same behaviour, but the defer cancel() guarantees cleanup whether or not the RPC finished.

Variant 5: a "rate-limited" log¶

var lastLog time.Time

func warn(msg string) {
    if time.Since(lastLog) < time.Second {
        return
    }
    lastLog = time.Now()
    log.Println(msg)
}

// ... called from a hot path ...
select {
case <-ch:
    warn("got value")
case <-time.After(timeout): // bug — fresh timer every call
    warn("idle")
}

The warn function is fine. The time.After is the leak. Same pattern, same fix.

Recognising the leak in pprof¶

Run pprof -alloc_space on a service that has been up for a while:

$ go tool pprof -alloc_space http://localhost:6060/debug/pprof/heap
(pprof) top10
Showing nodes accounting for 4.21GB, 92.45% of 4.55GB total
Dropped 154 nodes (cum <= 22.74MB)
      flat  flat%   sum%        cum   cum%
    2.31GB 50.78% 50.78%     2.31GB 50.78%  time.NewTimer
    1.45GB 31.87% 82.65%     3.76GB 82.65%  time.After
   ...

time.NewTimer and time.After at the top of -alloc_space is the unambiguous fingerprint. Drill down with list time.After to see exactly which call sites contributed.

In -inuse_space the numbers depend heavily on the Go version. Pre-1.23, the same call sites also dominate inuse. In 1.23+ the inuse shows much less because the GC can reclaim un-stopped timers. But -alloc_space always tells the truth about how many timers you constructed.

The goleak-style detection¶

goleak cannot directly tell you "you are leaking timers" — it tracks goroutines, not timers. But timer leaks often come with goroutine leaks (the goroutine waiting on time.After is still in the runtime's Gwaiting state). A growing runtime.NumGoroutine over time is a clue.

For unit tests, the simplest detector is:

func TestNoTimerLeak(t *testing.T) {
    base := runtime.NumGoroutine()
    // Run code under test.
    runUnderTest()
    runtime.GC()
    runtime.GC() // twice, to ensure finalizers run
    time.Sleep(50 * time.Millisecond)
    if got := runtime.NumGoroutine(); got > base+1 {
        t.Fatalf("goroutine leak: started=%d, ended=%d", base, got)
    }
}

This will catch the most common timer-related leak: a goroutine parked on <-time.After. It will not catch a leaked *time.Timer whose channel nobody is reading, but those are rare in practice.

The Phantom "default Saved Me" Myth¶

There is a folk wisdom in Go that adding default: to a select "fixes" the time.After leak. It does not. The myth comes from mixing up two different patterns.

The myth¶

for {
    select {
    case msg := <-ch:
        handle(msg)
    case <-time.After(5 * time.Second):
        log.Println("idle")
    default:
        // The default saves us from leaking the timer.
        runtime.Gosched()
    }
}

The claim: because the select has a default, the case <-time.After(...) will not block, and therefore the timer "is not used" and "does not leak."

This is wrong for two reasons.

Reason 1: time.After(...) is evaluated regardless¶

The expression time.After(5 * time.Second) is evaluated as part of building the select's case list. The runtime calls time.After, which allocates a *time.Timer, before the select decides which case wins. Adding default does not skip the evaluation of the other case expressions; it changes only which case is chosen if all of them would block.

In other words, the time.After allocation happens every iteration, default or no default. The timer is queued in the runtime heap. The timer fires 5 seconds later. The only thing default did was make the select return immediately, without reading from t.C or stopping the timer.

Reason 2: with default, the timer is more orphaned, not less¶

In the non-default version, at least the eventual <-time.After read drains the channel and the runtime cleans up.

In the default version, the timer goes into the heap, fires after 5 seconds, sends one value into its buffered channel (time.After's underlying channel has capacity 1), nobody reads from it ever, and the timer body sits in the heap until garbage collection picks it up.

Pre-Go 1.23, the GC could not pick it up until it had fired and been observed to be done. The body stayed alive for the full 5 seconds.

Go 1.23+ made unreferenced timers GC-collectible, so the body might be reclaimed sooner — but you still pay for the heap entry, the allocation, and the channel buffer until the runtime notices.

Demonstration¶

package main

import (
    "fmt"
    "runtime"
    "time"
)

func main() {
    for i := 0; i < 100_000; i++ {
        select {
        case <-time.After(5 * time.Minute):
        default:
        }
    }
    runtime.GC()

    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    fmt.Printf("alloc: %d KiB\n", m.Alloc/1024)
    fmt.Printf("total alloc: %d KiB\n", m.TotalAlloc/1024)
}

TotalAlloc will be in the hundreds of megabytes range. That is the proof: even with default, every iteration allocated a *time.Timer. The default did not save anything.

Why the myth exists¶

There is a real pattern where default is correct: the non-blocking drain we use after Stop:

if !t.Stop() {
    select {
    case <-t.C:
    default:
    }
}

Here default is exactly right. It says "read a value if there is one, otherwise carry on." But this is after the timer has been stopped and there is no fresh allocation happening. It is a different situation from the loop case.

The folk wisdom probably grew from someone seeing the drain pattern and generalising it to "default makes timers safe." It does not.

The correct fix is still a reusable timer¶

t := time.NewTimer(5 * time.Second)
defer t.Stop()

for {
    if !t.Stop() {
        select {
        case <-t.C:
        default:
        }
    }
    t.Reset(5 * time.Second)

    select {
    case msg := <-ch:
        handle(msg)
    case <-t.C:
        log.Println("idle")
    }
}

If you actually wanted "do work if available, otherwise yield" with no timeout, drop the timer entirely:

for {
    select {
    case msg := <-ch:
        handle(msg)
    default:
        runtime.Gosched()
    }
}

A select with default and no time-based case is fine. It is the combination of time.After and default that betrays misunderstanding.

AfterFunc and Stop Race Conditions¶

time.AfterFunc(d, f) schedules f to run on its own goroutine after d. It returns a *time.Timer, so you can call Stop() to cancel. The catch is that Stop does not synchronise with f itself.

The basic shape¶

t := time.AfterFunc(d, func() {
    cleanup()
})

// ... later ...
if !t.Stop() {
    // The callback already started (or finished). cleanup() may or may not have completed.
}

Stop returns false if the callback has already started running. It does not wait for the callback to finish. That is the subtle bug: you might think Stop returning false means the callback is done, but it may still be in flight.

A real race¶

type Conn struct {
    mu       sync.Mutex
    closed   bool
    timer    *time.Timer
}

func (c *Conn) Close() {
    c.mu.Lock()
    c.closed = true
    c.mu.Unlock()
    if c.timer != nil {
        c.timer.Stop()
    }
}

func (c *Conn) StartHeartbeat() {
    c.timer = time.AfterFunc(30*time.Second, func() {
        c.mu.Lock()
        defer c.mu.Unlock()
        if c.closed {
            return
        }
        c.sendPing()
    })
}

Even though Close calls Stop, the callback may already be in sendPing by the time Close returns. The closed check inside the callback is the only thing that saves you — and it is correct here because the callback re-acquires c.mu.

If you skip the closed check inside the callback, you get a use-after-close. Tests will sometimes fail, sometimes pass. Race detector finds it if you are lucky.

The synchronisation rule for AfterFunc¶

If your callback touches shared state, the callback must protect itself with the same lock that the outer code uses. Stop is best-effort. It tells you "the callback will not start from here onwards", not "the callback has finished."

If you need "definitely not running anymore", the canonical pattern is:

type SafeTimer struct {
    timer *time.Timer
    wg    sync.WaitGroup
}

func NewSafeTimer(d time.Duration, f func()) *SafeTimer {
    st := &SafeTimer{}
    st.wg.Add(1)
    st.timer = time.AfterFunc(d, func() {
        defer st.wg.Done()
        f()
    })
    return st
}

func (st *SafeTimer) Stop() {
    if !st.timer.Stop() {
        // Callback already started; wait for it to finish.
        st.wg.Wait()
    } else {
        // Callback never ran; mark wg done.
        st.wg.Done()
    }
}

Now Stop waits for the callback if it had started. Note: this only works if Stop is called at most once.

Leaks caused by callbacks holding state¶

AfterFunc's callback is a closure. Anything captured by that closure is kept alive until the timer fires or is stopped. If your callback captures a *Request that the caller already finished with, that request lives for an extra d duration.

Multiply by a hot RPC server and you have a leak that does not show up as goroutines but does show up as inuse_space in pprof.

The fix is usually to capture only the bits you need:

// Bad: captures the whole request.
time.AfterFunc(d, func() {
    if req.IsCancelled() {
        cleanup(req)
    }
})

// Better: capture just the cancellation signal.
done := req.Done()
id := req.ID
time.AfterFunc(d, func() {
    select {
    case <-done:
        cleanup(id)
    default:
    }
})

This is a tiny change, but at high volume it shrinks the live set noticeably.

AfterFunc is rarely the right tool¶

In review, ask: would context.WithTimeout or a single goroutine with a select do the job? AfterFunc is appealing because it does not need a goroutine of its own to read a channel — but it makes synchronisation strictly harder. Use it for fire-and-forget cleanups that do not interact with anything else. For anything coordinated, use NewTimer and a select.

Ticker Leaks and Misuse of time.Tick¶

A *time.Ticker is a recurring timer. It sends on t.C every d. You stop it with t.Stop(). If you do not, it ticks forever, and the runtime cannot reclaim the underlying timer until process exit.

The forgotten Stop¶

func runHeartbeat(server *Server) {
    t := time.NewTicker(time.Second)
    for {
        select {
        case <-t.C:
            server.Ping()
        case <-server.Done():
            return // BUG: forgot t.Stop()
        }
    }
}

The return exits the goroutine but leaves the ticker running. Every second, the runtime tries to deliver into t.C, which is buffered (capacity 1). Once the buffer fills, subsequent ticks are dropped — but the ticker keeps trying. The internal timer entry stays in the heap. Memory is pinned until process exit.

The fix is one line:

func runHeartbeat(server *Server) {
    t := time.NewTicker(time.Second)
    defer t.Stop()
    for {
        select {
        case <-t.C:
            server.Ping()
        case <-server.Done():
            return
        }
    }
}

defer t.Stop() is the same pattern as defer f.Close() for an open file. Make it muscle memory.

Multiple exit points¶

If you have several places that can exit the loop, the defer covers all of them:

func runHeartbeat(ctx context.Context, server *Server) error {
    t := time.NewTicker(time.Second)
    defer t.Stop()

    for {
        select {
        case <-t.C:
            if err := server.Ping(); err != nil {
                return err
            }
        case <-ctx.Done():
            return ctx.Err()
        case <-server.Done():
            return nil
        }
    }
}

One defer, three exits. The ticker stops in all cases.

time.Tick is unstoppable¶

for now := range time.Tick(time.Second) {
    log.Println("tick", now)
}

This is the textbook form. The for range loop reads from the channel time.Tick returns. Looks clean. But the ticker itself is never accessible, never stoppable, and never collectible. If the function returns, the ticker still fires every second for the rest of the process's life.

The godoc warning is explicit: time.Tick should be used only when you know the program will never need to stop the ticker. In practice, that means: never use time.Tick outside main or top-level setup code.

Bad:

func (s *Service) Run() {
    for t := range time.Tick(time.Second) {
        s.process(t)
    }
}

If s is destroyed, time.Tick keeps firing forever.

Good:

func (s *Service) Run(ctx context.Context) {
    tk := time.NewTicker(time.Second)
    defer tk.Stop()
    for {
        select {
        case t := <-tk.C:
            s.process(t)
        case <-ctx.Done():
            return
        }
    }
}

Tickers with a subscriber that exits¶

A common architecture: one goroutine creates a Ticker, another goroutine reads from t.C. If the reader dies and the creator does not notice, the ticker still fires. The buffered channel fills up, ticks are dropped, but the ticker entry stays in the timer heap.

To survive this, the goroutine that created the ticker should also be the goroutine that stops it. Co-locate creation and cleanup.

Diagnosing leaked tickers¶

pprof -inuse_space shows persistent allocations from time.NewTicker. The stack trace points at the line that created the leak. The fix is always the same: add a Stop.

A defensive habit: when you grep -r "time.NewTicker" . in your codebase, every result should have a Stop somewhere within ten lines below it. If it does not, you have a candidate leak.

Per-Connection Deadlines vs Timers¶

In network code, timeouts come in two flavours:

1. Deadlines on the connection: c.SetReadDeadline, c.SetWriteDeadline.
2. External timers that race against the I/O via select.

Beginners often write the second when the first would do the job. The second tends to leak.

Deadlines: in-kernel timeouts¶

c.SetReadDeadline(time.Now().Add(5 * time.Second))
n, err := c.Read(p)
// err includes a deadline-exceeded indicator if the deadline elapsed.

Internally, the runtime arranges for the read to return os.ErrDeadlineExceeded (or *net.OpError containing it) after the deadline. There is no external timer goroutine. There is one runtime timer entry per connection, replaced each time you call SetReadDeadline.

When you Close the connection, the deadline timer is cancelled. No leak.

External timers: goroutine + select¶

done := make(chan error, 1)
go func() {
    _, err := c.Read(p)
    done <- err
}()

select {
case err := <-done:
    return err
case <-time.After(5 * time.Second):
    return errReadTimeout
}

Two problems:

• The goroutine continues to block in c.Read even after the timeout. If c.Read never returns (because the peer never sends and there is no deadline on the conn), that goroutine leaks forever.
• The time.After allocates a fresh timer per call.

Use deadlines:

c.SetReadDeadline(time.Now().Add(5 * time.Second))
n, err := c.Read(p)
if err != nil {
    if errors.Is(err, os.ErrDeadlineExceeded) {
        return errReadTimeout
    }
    return err
}

No goroutine, no timer churn, no leak. The trade-off is that deadlines work only for I/O operations that respect them — c.Read, c.Write, the net.Conn interface. They do not help with arbitrary blocking operations (e.g., a sync.Mutex.Lock you would like to timeout).

The lock-with-timeout antipattern¶

done := make(chan struct{})
go func() {
    mu.Lock()
    close(done)
}()

select {
case <-done:
    defer mu.Unlock()
    // ... use the protected resource ...
case <-time.After(time.Second):
    // Timeout. But the goroutine is still trying to acquire the lock.
    // When it eventually does, nobody will Unlock.
}

Here both the goroutine and the timer leak. Once the lock is acquired by the orphan goroutine, the resource is permanently inaccessible. This is one of the most insidious bugs in concurrent Go.

The fix: do not put a timeout on a sync.Mutex.Lock. If you must timeout, use a channel-based mutex (a chan struct{} of capacity 1), where Lock is <-ch and Unlock is ch <- struct{}{}. Then select { case <-ch: ; case <-timeout: } gives you a real timeout without an orphaned goroutine.

type lock chan struct{}

func newLock() lock {
    l := make(lock, 1)
    l <- struct{}{}
    return l
}

func (l lock) Lock()   { <-l }
func (l lock) Unlock() { l <- struct{}{} }

// Lock with timeout:
func (l lock) TryLockFor(d time.Duration) bool {
    t := time.NewTimer(d)
    defer t.Stop()
    select {
    case <-l:
        return true
    case <-t.C:
        return false
    }
}

No leak. The select either acquires the lock or times out. If the timer wins, the lock channel was simply not read. The other goroutine holding the lock will eventually release it, and a future caller can acquire.

A connection pool example¶

In a connection pool you often want "get me a conn within 100ms or fail." The channel-based pool is a natural fit:

type Pool struct {
    free chan *Conn
}

func (p *Pool) Get(d time.Duration) (*Conn, error) {
    t := time.NewTimer(d)
    defer t.Stop()
    select {
    case c := <-p.free:
        return c, nil
    case <-t.C:
        return nil, errPoolTimeout
    }
}

One reusable timer per call, stopped at return. The timer body is in the heap for the duration of the wait — at most d — which is fine because that is what d is for.

If Get is called in a hot loop:

for {
    c, err := pool.Get(100 * time.Millisecond)
    if err != nil {
        return err
    }
    ...
}

The per-call NewTimer is one allocation per call. On Go 1.23 this is fast. On older Go, in a tight loop, you might reuse the timer:

func (p *Pool) GetWithTimer(t *time.Timer, d time.Duration) (*Conn, error) {
    resetTimer(t, d)
    select {
    case c := <-p.free:
        // We have a connection. Stop the timer.
        if !t.Stop() {
            select {
            case <-t.C:
            default:
            }
        }
        return c, nil
    case <-t.C:
        return nil, errPoolTimeout
    }
}

Callers reuse a single *time.Timer across many GetWithTimer calls. Allocations drop to zero. Worth it only if the profile shows NewTimer in the top contributors.

Testing Timer-Heavy Code¶

Code that depends on real time is hard to test deterministically. Two common approaches:

1. Inject a Clock interface. The production clock returns time.Now() and time.NewTimer. The test clock returns a manually advanced now and a fake timer.
2. Run with very short durations (microseconds) so wall-clock variance is irrelevant.

Clock interface¶

type Clock interface {
    Now() time.Time
    NewTimer(d time.Duration) Timer
}

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

type realClock struct{}

func (realClock) Now() time.Time            { return time.Now() }
func (realClock) NewTimer(d time.Duration) Timer { return realTimer{time.NewTimer(d)} }

type realTimer struct{ *time.Timer }

func (r realTimer) Chan() <-chan time.Time { return r.C }

Production code accepts a Clock. Tests pass a fake clock whose NewTimer returns a fake timer with a manually controlled channel.

Fake clock¶

type fakeClock struct {
    mu  sync.Mutex
    now time.Time
    timers []*fakeTimer
}

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

func (c *fakeClock) NewTimer(d time.Duration) Timer {
    c.mu.Lock()
    defer c.mu.Unlock()
    t := &fakeTimer{
        ch:    make(chan time.Time, 1),
        fires: c.now.Add(d),
    }
    c.timers = append(c.timers, t)
    return t
}

func (c *fakeClock) Advance(d time.Duration) {
    c.mu.Lock()
    c.now = c.now.Add(d)
    fires := c.now
    var toFire []*fakeTimer
    var keep []*fakeTimer
    for _, t := range c.timers {
        if !t.stopped && !fires.Before(t.fires) {
            toFire = append(toFire, t)
        } else {
            keep = append(keep, t)
        }
    }
    c.timers = keep
    c.mu.Unlock()
    for _, t := range toFire {
        select {
        case t.ch <- fires:
        default:
        }
    }
}

type fakeTimer struct {
    ch      chan time.Time
    fires   time.Time
    stopped bool
}

func (t *fakeTimer) Chan() <-chan time.Time { return t.ch }
func (t *fakeTimer) Stop() bool {
    if t.stopped {
        return false
    }
    t.stopped = true
    return true
}
func (t *fakeTimer) Reset(d time.Duration) bool { /* ... */ return false }

Now a test can:

func TestIdleTimeout(t *testing.T) {
    clock := &fakeClock{now: time.Unix(0, 0)}
    s := NewServer(clock)
    go s.Run()

    clock.Advance(5 * time.Second)
    if !s.WasMarkedIdle() {
        t.Fatal("expected idle after 5s")
    }
}

No real sleeping. No flakiness.

Short real durations¶

For simple cases:

func TestIdleTimeoutFast(t *testing.T) {
    s := NewServer()
    s.idleTimeout = 10 * time.Millisecond
    go s.Run()

    time.Sleep(50 * time.Millisecond)
    if !s.WasMarkedIdle() {
        t.Fatal("expected idle after 10ms")
    }
}

Simpler but slower and flakier under CI load. Good for smoke tests, not for tight assertions.

goleak for goroutine leaks¶

func TestMain(m *testing.M) {
    goleak.VerifyTestMain(m)
}

This catches goroutines that did not exit by the end of the test. If your timer code leaks a goroutine (the most common symptom of a timer leak), goleak will fail the test.

For finer control:

func TestRun(t *testing.T) {
    defer goleak.VerifyNone(t)
    s := NewServer()
    s.Run(time.Millisecond)
    s.Close()
}

If Close does not stop the ticker, goleak reports the goroutine that is parked on the ticker channel.

Detection Cheatsheet¶

A printable checklist for production:

Symptoms¶

• RSS of the process grows monotonically over hours.
• runtime.MemStats.HeapAlloc grows but does not free between GCs.
• runtime.NumGoroutine() grows over time.
• pprof /debug/pprof/goroutine?debug=2 shows many goroutines parked in time.Tick, time.After, time.NewTimer.

Commands¶

# Goroutine stack dump
curl -s localhost:6060/debug/pprof/goroutine?debug=2 > goroutines.txt
grep -c "time.After\|time.Tick\|time.NewTimer" goroutines.txt

# Heap profile, by allocation count (catches "made too many")
go tool pprof -alloc_space http://localhost:6060/debug/pprof/heap
(pprof) top time
(pprof) list time.After

# Heap profile, by in-use bytes
go tool pprof -inuse_space http://localhost:6060/debug/pprof/heap
(pprof) top time

Runtime tracepoints¶

import "runtime/trace"

f, _ := os.Create("trace.out")
defer f.Close()
trace.Start(f)
defer trace.Stop()

// run service under load

Then go tool trace trace.out and look at the "Goroutines" and "Syscall" panes. Timer-related goroutines show up as long parked spans.

runtime.MemStats watchpoints¶

go func() {
    t := time.NewTicker(time.Minute)
    defer t.Stop()
    for range t.C {
        var m runtime.MemStats
        runtime.ReadMemStats(&m)
        log.Printf("alloc=%dMB sys=%dMB goroutines=%d",
            m.HeapAlloc>>20, m.Sys>>20, runtime.NumGoroutine())
    }
}()

Plot alloc and goroutines over time. Trend up means leak.

Quick triage decision tree¶

1. Is runtime.NumGoroutine rising?
2. Yes → look for parked goroutines on time.After / Tick / NewTimer.
3. No → look at pprof -alloc_space.
4. Is time.After or time.NewTimer in pprof top?
5. Yes → find the call site in a loop. Replace with reusable timer.
6. No → not a timer leak. Look elsewhere.
7. Is time.NewTicker in pprof inuse?
8. Yes → find the NewTicker call. Check defer t.Stop() exists on every code path.
9. No → check time.Tick. If used outside main, replace with NewTicker.

Refactor Walkthroughs¶

Three before/after refactors at increasing scale.

Refactor 1: a chat server's read loop¶

Before¶

func (c *Client) readLoop() {
    for {
        select {
        case <-c.done:
            return
        case msg := <-c.in:
            c.handle(msg)
        case <-time.After(c.idleTimeout):
            c.markIdle()
            return
        }
    }
}

Allocation per iteration. In a busy chat server with 10 000 concurrent clients each receiving messages at 5 per second, that is 50 000 timers per second.

After¶

func (c *Client) readLoop() {
    t := time.NewTimer(c.idleTimeout)
    defer t.Stop()
    for {
        if !t.Stop() {
            select {
            case <-t.C:
            default:
            }
        }
        t.Reset(c.idleTimeout)
        select {
        case <-c.done:
            return
        case msg := <-c.in:
            c.handle(msg)
        case <-t.C:
            c.markIdle()
            return
        }
    }
}

One timer per client for the lifetime of the connection.

Result (synthetic numbers)¶

The "active timers" number actually went up — because every client now keeps a single timer permanently. That is correct and desired. What changed is the allocation rate and the retention time of completed timers.

Refactor 2: a sweeper goroutine¶

Before¶

func (s *Store) sweep(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            return
        case <-time.Tick(s.sweepInterval): // bug: time.Tick
            s.removeExpired()
        }
    }
}

The time.Tick creates a new ticker each iteration of the select. Worse than time.After, because every leaked ticker keeps firing forever.

Wait, does it actually? Let us be precise. time.Tick returns a <-chan Time that ticks forever. The select evaluates time.Tick(s.sweepInterval) each time the select is reached — every iteration of the for loop. Each evaluation creates a fresh *time.Ticker whose channel is wired to the select arm. The previous ticker is unreferenced — but unlike *Timer, a *Ticker keeps trying to fire forever, holding the channel reference until process exit.

So: yes, this leak grows without bound. Every loop iteration creates a new leaked ticker.

After¶

func (s *Store) sweep(ctx context.Context) {
    t := time.NewTicker(s.sweepInterval)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            return
        case <-t.C:
            s.removeExpired()
        }
    }
}

One *Ticker, stopped on exit.

Refactor 3: per-request timeout in an HTTP handler¶

Before¶

func (h *Handler) HandleRequest(w http.ResponseWriter, r *http.Request) {
    done := make(chan *Response, 1)
    go func() {
        done <- h.backend.Call(r.Context(), r)
    }()
    select {
    case resp := <-done:
        respond(w, resp)
    case <-time.After(2 * time.Second):
        http.Error(w, "timeout", http.StatusGatewayTimeout)
    }
}