time.AfterFunc — Senior Level¶

Table of Contents¶

1. Introduction
2. What This File Adds
3. The Runtime Timer Model
4. runtimeTimer in Detail
5. The Timer Heap, P-Local
6. When the Callback is Scheduled
7. Stop in the Runtime
8. Reset in the Runtime
9. The Pre-1.23 and Post-1.23 Eras
10. Memory Layout and Allocation
11. Latency Characteristics
12. Cost at Scale
13. Interaction with the Scheduler
14. Network Polling and Timers
15. GC and Timers
16. Profiling Timer Behaviour
17. Architectural Patterns
18. Senior-Level Exercises
19. Senior-Level Tricky Questions
20. Cheat Sheet
21. Self-Assessment
22. Summary
23. Further Reading
24. Diagrams

Introduction¶

This file is about what is actually happening inside the Go runtime when you call time.AfterFunc. Some of this knowledge is necessary to design systems that handle hundreds of thousands of timers; some of it is just deeply satisfying.

By the end of this file you will:

• Have read or mentally simulated the relevant parts of runtime/time.go.
• Be able to explain what runtimeTimer looks like, where it lives, and how it gets there.
• Understand the P-local timer heap and how the runtime decides which P's heap a timer joins.
• Know when and where the callback goroutine is spawned.
• Understand the meaning of every byte of Stop()'s and Reset()'s return.
• Know the difference between pre-1.23 timers (with timerStatus constants) and the post-1.23 simplification.
• Understand timer cost at scale (10K, 100K, 1M timers): heap depth, scheduler poll cost, GC pressure.
• Be able to recommend or design batching strategies for high-cardinality timer workloads.

You do not need to know the runtime in its entirety; we restrict ourselves to the timer machinery and adjacent scheduler code.

What This File Adds¶

junior.md and middle.md treat AfterFunc as a black box with well-defined semantics. This file opens the box. We will:

• Trace a single AfterFunc(d, f) call from user code to the heap insertion.
• Trace a single fire from heap pop to goroutine spawn.
• Show what Stop actually does — which fields it touches and which transitions it makes.
• Compare the pre-1.23 timer state machine (with timerNoStatus, timerWaiting, timerModifiedLater, etc.) to the post-1.23 simplified machine.
• Explain why Reset once had a "drain dance" and now does not.
• Quantify the cost of a million timers.

The Runtime Timer Model¶

One model, three views¶

We can describe Go's timer machinery at three levels of abstraction:

View 1 — User API. time.AfterFunc(d, f) -> *Timer. Callback runs in a goroutine. Stop and Reset work as documented.

View 2 — Runtime data structures. Each P (logical processor) has a heap of pending timer entries. A timer entry is a runtimeTimer with fields like when, period, f, arg, seq, and status. The runtime polls these heaps from various places.

View 3 — Implementation files. runtime/time.go and runtime/proc.go (or runtime/lock_futex.go etc. for the netpoller integration). Reading these files is the most precise way to understand the model.

This file works mostly at View 2, dropping into View 3 occasionally to anchor claims to real code.

What is a "P"?¶

A P (logical processor) is the Go runtime's unit of scheduling. By default, there is one P per CPU core (GOMAXPROCS=NumCPU). Each P has its own goroutine run queue and its own timer heap. P's also share work via a global queue and stealing.

For timers, the key fact is: a P owns a min-heap of runtimeTimer entries, indexed by their when field.

How a timer lands on a P¶

When time.AfterFunc is called from a goroutine running on P n, the timer is inserted into P n's local heap. (There are some special cases — for example, the global P 0's heap during startup — but in steady state, a timer joins the local P's heap.)

The timer stays on that P's heap unless the P is destroyed (during GOMAXPROCS reduction). If P n is gone, the timer migrates to another P's heap as part of P shutdown.

How a timer fires¶

When a P needs to pick the next work to run — for example, in its main scheduler loop, or at certain housekeeping points — it checks its local timer heap. The min-element's when is compared to the current monotonic time. If when <= now, the timer is "ready."

For an AfterFunc timer (one with a non-nil f and nil C), "ready" means:

1. Pop the timer from the heap.
2. Mark the timer as fired.
3. Spawn a goroutine to run f.

The newly spawned goroutine joins the P's run queue (or another P's, depending on load balancing).

runtimeTimer in Detail¶

The struct (post-1.23 simplified view)¶

// Approximate; the actual struct lives in runtime/time.go.
type timer struct {
    next     *timer
    prev     *timer

    when     int64           // monotonic time, in ns
    period   int64           // for repeating; 0 for one-shot
    f        func(any, uintptr) // the function to run
    arg      any
    seq      uintptr

    status   atomic.Uint32   // pre-1.23: timerWaiting, timerModified...
                             // post-1.23: simpler state
    nextWhen int64           // pre-1.23 only

    // ...
}

The user's time.Timer struct wraps this:

type Timer struct {
    C <-chan Time
    r runtimeTimer // The runtime's view of this timer
}

For an AfterFunc timer:

• C is nil.
• r.f is a small wrapper that calls the user's callback.
• r.arg carries the user's function value.

The wrapper exists because the runtime's f signature is func(any, uintptr), not func(). The wrapper unwraps and invokes the user's function.

The wrapper, conceptually¶

// Approximate.
func goFunc(arg any, _ uintptr) {
    go arg.(func())() // spawn a goroutine running the user's f
}

This is why the callback runs in a new goroutine — the wrapper unconditionally does go arg.(func())(). There is no path where the callback runs synchronously.

when is monotonic¶

when is stored as an int64 nanoseconds value on the monotonic clock. The runtime uses nanotime() to read it, never time.Now(). This is why wall-clock adjustments do not perturb timers.

A time.Duration of 0 means when = now. A negative duration means when < now, which the runtime treats as "fire immediately."

period is 0 for AfterFunc¶

AfterFunc always sets period = 0. The runtime knows that means "one-shot."

For time.NewTicker, the same runtimeTimer is used with a non-zero period, and after firing, the runtime advances when += period and re-inserts. AfterFunc does not use this; for repetition, you self-reschedule with Reset from inside the callback.

seq¶

The seq field is used for identification in some accounting paths. For us, treat it as opaque.

The Timer Heap, P-Local¶

A 4-ary min-heap¶

Each P holds its timers in a min-heap implementation. The heap is keyed on when. Historically the heap is 4-ary (each node has up to 4 children), chosen for cache efficiency. The exact arity is an implementation detail.

Operations on the heap:

• siftup after insertion (when a new entry is added).
• siftdown after removal (when the top is popped or a deletion happens).
• peek to check the earliest when.

All these are O(log n).

Why P-local¶

A global heap of all timers would require global synchronisation on every insertion, deletion, and check. By making the heap P-local, the runtime amortises the cost across cores. Each P touches only its own heap most of the time.

When P n runs out of work, it may "steal" goroutines from another P; the equivalent for timers exists but is rarer.

Timer-heap maintenance¶

The runtime checks the heap during:

• The scheduler loop, when picking the next goroutine to run.
• The sysmon goroutine, which wakes up periodically to handle things.
• runtime.GC() and related calls.
• The netpoller, when waking from a network event.
• runtime.Gosched() (briefly).

So "the timer fires after d" is really "the runtime notices it sometime after d, when it next does a scheduler iteration."

Throughput vs. latency tradeoff¶

The runtime balances:

• Latency: firing the timer near the requested time.
• Throughput: not spending too much CPU polling.

In practice this means firing latency is sub-millisecond on a lightly loaded system, and can climb under load. For wall-clock precision better than ~1 ms, do not rely on Go timers.

When the Callback is Scheduled¶

Two phases: pop and spawn¶

When a P notices an expired timer on its heap, the runtime executes:

1. Lock the timer's status.
2. Remove the timer from the heap.
3. Unlock.
4. Call the timer's f with its arg.

For an AfterFunc timer, f is the wrapper that does go userFunc(). So step 4 spawns a goroutine.

Spawn cost¶

Spawning a goroutine is cheap (allocate from a pool of free goroutine descriptors, set up the stack, push to the run queue). A few hundred nanoseconds typical.

Scheduler latency on top¶

The spawned goroutine joins the P's run queue. The runtime will run it next, or after the currently-running goroutine yields. Under low load this means "almost immediately." Under high load it may wait microseconds or milliseconds.

Why not run f directly?¶

A simpler model would be: the runtime calls f synchronously, on the current goroutine, when it notices the timer. This has problems:

• f could be slow, delaying scheduler work.
• f could block, halting the P entirely.
• f could be malicious or buggy, breaking runtime invariants.

By spawning a goroutine, the runtime isolates f from the scheduler. The cost is the goroutine spawn; the benefit is robustness.

Multiple expired timers¶

If the heap has 10 expired timers, the runtime pops each and spawns 10 goroutines. They run in parallel (subject to GOMAXPROCS) and there is no ordering guarantee among them.

Stop in the Runtime¶

What Stop() does¶

func (t *Timer) Stop() bool {
    return stopTimer(&t.r)
}

stopTimer looks at t.r.status (in pre-1.23) or invokes a state transition (in post-1.23). If the timer is currently in a P's heap, it removes it. The return value is whether the removal happened.

Pre-1.23 status states¶

timerNoStatus       // freshly created, not yet on a heap
timerWaiting        // on the heap, not yet expired
timerRunning        // f is currently being called (briefly)
timerDeleted        // marked for removal
timerRemoving       // in the process of being removed
timerRemoved        // removed
timerModifying      // someone is mutating
timerModifiedEarlier
timerModifiedLater
timerMoving         // being moved to another P

The full state machine had ~10 states and was source of subtle bugs and locking complexity. Each method on the timer (Stop, Reset, the runtime's "fire" path) had to handle all the states.

Post-1.23 simplification¶

Go 1.23 reorganised timers around an atomic head and a much simpler state model. The user-visible behaviour is unchanged; the internal representation is cleaner.

For our purposes, the post-1.23 state model has effectively:

• "Active" (on a heap).
• "Inactive" (not on a heap).

Stop succeeds iff the timer was active and is now inactive. Reset is similar but conditional on the prior state for its return value.

Stop's locking¶

Stop takes the P's timer-heap lock briefly to remove the entry. It is a short critical section. There is no user-visible blocking — Stop does not wait for the callback's goroutine.

Stop returning false: three flavours¶

We can distinguish three reasons Stop returns false:

1. The timer had already fired (callback running or done).
2. The timer was already stopped (by a previous Stop).
3. The timer never existed (programmer error — using a zero time.Timer).

The user-facing API does not distinguish these. From the runtime's perspective:

• Case 1: pre-1.23 status was timerRemoved or timerRunning; post-1.23 status was "not on heap."
• Case 2: same as case 1, since both Stop and "fire then remove" land in the same state.
• Case 3: the timer's r field is zero; the runtime returns false.

If you need to know case 1 vs case 2, you must track yourself.

Reset in the Runtime¶

What Reset does¶

func (t *Timer) Reset(d Duration) bool {
    return resetTimer(&t.r, when(d))
}

resetTimer updates the timer's when to now + d and ensures it is on a heap. The return value reflects whether the timer was active before the call.

Reset on active timer¶

1. Lock the timer's status.
2. Remove from the current heap position.
3. Update when.
4. Reinsert into the heap.
5. Unlock.

Cost: O(log n) for the reinsert, plus locking overhead.

Reset on inactive timer¶

1. Lock the timer's status.
2. Update when.
3. Insert into the heap.
4. Unlock.

The boolean return is false in this case.

Reset on a timer that has fired but is still being processed¶

There is a very brief window where the timer is "running" (the runtime has popped it, is about to call f). During this window, Reset will see the running state and either wait or fail. Pre-1.23 this had its own state; post-1.23 the runtime serialises around f invocation.

Reset and lock ordering¶

If you Reset from inside the callback f, the runtime is in the middle of "running" the timer. The Reset call must not deadlock. The implementation handles this by avoiding recursive locks on the timer state.

In practice, Reset inside f "just works" — you don't need to think about it.

The Pre-1.23 and Post-1.23 Eras¶

A short history.

Pre-1.10: wall clock¶

Before Go 1.10, timers were based on the wall clock. If the system clock jumped forward (NTP, daylight savings), pending timers fired immediately. If it jumped backward, they fired late. This caused havoc.

Go 1.10: monotonic clock¶

time.Time gained a monotonic component. Timers now use the monotonic clock. Wall-clock adjustments don't perturb them.

Go 1.14: async preemption¶

Long-running goroutines (including timer callbacks!) can be preempted by the runtime, regardless of whether they reach a safe point. This makes "callback runs for a long time" safer for the rest of the program.

Go 1.18: timer rewrite¶

The internal representation was rewritten for performance, but with the same timerStatus constants. Many subtle bugs in the old implementation were resolved.

Go 1.21: context.AfterFunc¶

Added as a peer to time.AfterFunc for context-driven scheduling.

Go 1.23: simplification¶

The timerStatus constants were reduced; the drain dance for Reset became unnecessary. The implementation became significantly easier to reason about.

Go 1.24: synctest¶

testing/synctest allows deterministic time-driven tests.

For the user-facing API: time.AfterFunc(d, f) -> *Timer, Stop, Reset have been stable since Go 1.0.

Memory Layout and Allocation¶

Allocations¶

A single time.AfterFunc(d, f) call allocates:

• One time.Timer struct (heap-allocated; the runtime keeps a reference).
• Possibly a closure on the heap (if f is a closure capturing variables).
• The time.Timer's r runtimeTimer is embedded; no separate allocation.

A reused *Timer via Reset(d) allocates nothing in user code. The same *Timer is reused; the same closure is reused.

Cost per timer¶

Each timer occupies roughly:

• ~120 bytes for the runtimeTimer (varies by Go version and platform).
• Plus the size of the closure (closure header + captured variables).
• Plus heap-bookkeeping overhead.

A million timers thus use ~150–250 MB just for the timer structs, plus whatever the closures hold.

Closure size¶

A closure capturing only ints is small (~24 bytes). A closure capturing a *Request pointer is small but pins the request. A closure capturing a 1 KB buffer pins 1 KB.

This is why "what does the closure capture?" is the most important question for timer-heavy services.

Pooling¶

The runtime maintains an internal pool of runtimeTimer slabs to reduce allocation pressure under churn. Reused timers come from this pool. You cannot inspect it from user code, but the effect is that creating and stopping many timers is cheaper than creating and never stopping them — because stopped timers can be reused, while never-stopped ones cannot until they fire.

Latency Characteristics¶

Best case¶

Sub-millisecond. On a lightly loaded machine, a 10 ms AfterFunc typically fires within ~10.05 ms.

Worst case¶

Under heavy load (CPU pinned, GC active), individual timer fires can be late by 10s of milliseconds. Catastrophic cases (GC stop-the-world phases in pre-1.14 Go) could be 100s of ms.

Jitter sources¶

• Scheduler polling interval — the runtime checks the heap at scheduler iterations, which happen on goroutine yields, blocking calls, and periodically.
• GC — though sub-millisecond pauses are typical, busy GC can add several hundred microseconds.
• OS thread contention — if all OS threads are busy doing other work, timer firing is delayed.
• Power management — on laptops with C-states, sub-millisecond timers can be late by milliseconds.

Don't rely on precision¶

For deadlines that matter to users (e.g. "this request must complete within 200 ms"), set the timer for slightly less than the deadline (e.g. 150 ms) to give yourself slack.

Cost at Scale¶

Small (1–100 timers)¶

Negligible. Don't think about it.

Medium (100–10K timers)¶

Still negligible. Heap operations are O(log n) ≤ 14 even at 10K.

Large (10K–100K timers)¶

Visible in profiles. runtime.siftdownTimer and similar functions appear in CPU profiles. The runtime spends some CPU on heap maintenance.

Very large (100K–1M timers)¶

Significant. Memory budget for timers alone runs into hundreds of MB. CPU for heap operations is several percent. The number of goroutine spawns at fire time can be a spike — many goroutines firing simultaneously stresses the GC and the scheduler.

Pathological (>1M timers)¶

You should not be doing this. If your design requires it, consider batching, sharding (timers grouped by deadline bucket), or moving to a custom timing structure (e.g., a hierarchical timing wheel — see Varghese & Lauck 1996).

Sharding pattern¶

Instead of one timer per entry, group entries by deadline bucket (e.g. round to the nearest 100 ms):

type Bucket struct {
    deadline time.Time
    entries  []entry
    timer    *time.Timer
}

func (s *Scheduler) Schedule(e entry) {
    bucket := s.bucketFor(e.deadline.Truncate(100 * time.Millisecond))
    bucket.entries = append(bucket.entries, e)
    if bucket.timer == nil {
        bucket.timer = time.AfterFunc(time.Until(bucket.deadline), bucket.fire)
    }
}

A million entries with 1-second buckets becomes ~1000 timers. Much more manageable.

Hierarchical timing wheel¶

For truly extreme scale (millions of timers, sub-millisecond accuracy), hierarchical timing wheels are the textbook structure. Insertion and deletion are O(1) amortised. The Linux kernel uses this for its timer_list interface. Go's standard library does not — the heap is simpler and good enough for most use cases.

Interaction with the Scheduler¶

Scheduler P loop¶

Each P runs a loop that picks the next runnable goroutine. At certain points it checks runtime.checkTimers (or equivalent) to fire any expired timers on its local heap. This is how timers are integrated with normal scheduler work — no separate "timer thread."

When P is idle¶

If all P's are idle (no goroutines to run), the runtime parks them. But it needs to wake up when a timer is about to fire. The runtime computes "when is the next timer?" and schedules a wakeup (typically via futex on Linux or equivalent).

This means: even with no work to do, a Go program with pending timers wakes the CPU periodically. For battery-powered devices, lots of pending timers can drain battery.

When P is busy¶

A P that is running a long goroutine still checks timers periodically. The async preemption signal (Go 1.14+) ensures this happens within a few milliseconds at most.

sysmon¶

The sysmon goroutine is a background goroutine that wakes up periodically (every 20 µs typically, backing off) to handle housekeeping: nudging stalled P's, retaking syscall-blocked P's, checking timers. It is a backup for timer firing in cases where the normal scheduler loop misses.

Network Polling and Timers¶

The netpoller¶

Go's network I/O is implemented via the netpoller, which uses epoll on Linux, kqueue on BSD, IOCP on Windows. The poller goroutine blocks on a system call waiting for I/O readiness; when something arrives, it wakes goroutines.

The netpoller is also responsible for waking on timer expirations. When parking on epoll_wait (or equivalent), the runtime computes the timeout as "duration until next timer" and passes it. If no I/O arrives, the call returns at the timeout, the runtime fires timers, and life continues.

This integration is why timers fire promptly even when the program is idle on I/O.

Implication¶

If your program is mostly waiting on the netpoller (e.g. a server doing nothing because no requests are coming), timer accuracy is good — the netpoller's timeout drives wakeups.

If your program is mostly compute (a CPU-bound loop), timer accuracy depends on async preemption. Still good, but with more jitter.

GC and Timers¶

Timers and the GC¶

runtimeTimer entries are heap-allocated. The GC scans them like any other heap object. The f field references a function value; the function value's closure (if any) is also on the heap.

For each live timer, the chain is:

timer entry -> f (function value) -> closure -> captured variables

The GC visits all of these. For a million timers each capturing a 1 KB struct, that is 1 GB of pinned heap that the GC has to traverse.

Stop and GC¶

When you Stop a timer and drop your reference, the runtime's reference to the timer entry should also go away (the entry is removed from the heap). The GC will then collect everything reachable only from the timer.

However: if you stored the *time.Timer in a map and forgot to delete the map entry, the timer entry and its closure remain reachable. Classic leak.

Timer churn and GC pressure¶

Creating and stopping many timers per second creates allocation pressure. The runtime mitigates with a pool, but high-frequency churn can still trigger more frequent GC cycles.

Recommendation¶

For high-frequency scheduling, prefer Reset on a reused timer. The allocation count drops dramatically.

Profiling Timer Behaviour¶

CPU profile¶

go tool pprof http://localhost:6060/debug/pprof/profile

Look for runtime.siftdownTimer, runtime.siftupTimer, runtime.checkTimers, runtime.addtimer, runtime.modtimer. High percentages in these functions indicate heavy timer activity.

Heap profile¶

go tool pprof http://localhost:6060/debug/pprof/heap

Look for allocations stemming from time.AfterFunc or time.NewTimer. If timers dominate the heap, you may need to switch to a batching strategy.

Goroutine profile¶

go tool pprof http://localhost:6060/debug/pprof/goroutine

If you have many goroutines stuck in time.Sleep or <-time.After, that is a candidate for AfterFunc replacement (no parked goroutine).

runtime.MemStats¶

MemStats.NumGoroutine for the goroutine count.

Tracing¶

GODEBUG=schedtrace=1000 ./your-program

Prints scheduler stats every second, including run queue lengths. Spikes correlate with timer fire bursts.

go tool trace trace.out

The execution trace visualises goroutine spawns from timer fires.

Profiling AfterFunc specifically¶

There is no first-class "timer profile" in pprof, but the CPU profile attribution to timer-related functions is usually enough. If you suspect a leak (timers piling up), use the heap profile and look at the retention chain.

Architectural Patterns¶

Pattern 1: One timer per resource¶

Used in IdleConn, simple TTL caches, per-request deadlines. Works well up to ~100K resources. Beyond that, switch to batching.

Pattern 2: Single sweeper¶

One periodic timer fires and processes all expired entries. Used in many in-memory caches.

func (c *Cache) sweep() {
    c.mu.Lock()
    now := time.Now()
    for k, exp := range c.expiry {
        if exp.Before(now) {
            delete(c.items, k)
            delete(c.expiry, k)
        }
    }
    c.mu.Unlock()
    time.AfterFunc(c.sweepInterval, c.sweep)
}

Sweeping is O(n) in the cache size; acceptable for small caches or when sweep frequency is low.

Pattern 3: Earliest-deadline timer¶

Keep a sorted data structure of deadlines. Set one *time.Timer for the earliest deadline. When it fires, process all entries due, then re-arm for the next earliest deadline.

type Scheduler struct {
    mu       sync.Mutex
    timer    *time.Timer
    pending  *deadlineHeap // entries sorted by deadline
}

func (s *Scheduler) arm() {
    s.mu.Lock()
    defer s.mu.Unlock()
    if s.pending.Len() == 0 {
        return
    }
    next := s.pending.Peek()
    d := time.Until(next.deadline)
    if d < 0 { d = 0 }
    if s.timer == nil {
        s.timer = time.AfterFunc(d, s.fire)
    } else {
        s.timer.Reset(d)
    }
}

func (s *Scheduler) fire() {
    s.mu.Lock()
    now := time.Now()
    var due []entry
    for s.pending.Len() > 0 && !s.pending.Peek().deadline.After(now) {
        due = append(due, s.pending.Pop())
    }
    s.mu.Unlock()
    for _, e := range due {
        go e.handler() // or whatever
    }
    s.arm()
}

Each operation is O(log n) — heap insert/remove. Total memory is O(n). This pattern scales to millions of entries with sub-millisecond response.

Pattern 4: Hashed timing wheel¶

A circular buffer of buckets, each bucket holds a list of entries due in that bucket's time slice. Insertion and removal are O(1) amortised. A "current bucket" pointer advances every tick.

For implementations and tradeoffs, see Varghese & Lauck 1996, "Hashed and Hierarchical Timing Wheels."

Not in the Go standard library, but plenty of third-party libraries implement it (e.g. for game servers, network monitoring).

Pattern 5: Coarse-grained ticker + work queue¶

Drop per-entry timers entirely. Have a coarse ticker (every 100 ms) that scans for entries to process. Submit them to a worker pool.

ticker := time.NewTicker(100 * time.Millisecond)
for range ticker.C {
    for _, e := range expired() {
        workQueue <- e
    }
}

Loses sub-100ms accuracy. Gains scalability — no timer scaling concerns at all. Used in many high-throughput systems where deadlines are "fire-and-forget."

Senior-Level Exercises¶

E1. Read runtime/time.go¶

Open the Go source for your installed version. Read addtimer, deltimer, modtimer, and runtimer. Sketch the state diagram.

E2. Measure timer overhead¶

Write a benchmark that creates and stops N timers. Plot N vs. time. Verify O(N log N) for creation plus stop.

E3. Build the earliest-deadline scheduler¶

Implement Pattern 3 above. Compare its memory and CPU profile to per-entry timers at 1K, 10K, 100K, 1M entries.

E4. Verify the fire latency distribution¶

Schedule 10K timers all firing in 1 second. Record (actual_fire_time - scheduled_fire_time) for each. Plot the distribution. Compute p50, p99, p999.

E5. Build a hashed timing wheel¶

In Go. Aim for O(1) insertion, deletion, and tick processing.

E6. Compare AfterFunc and After in a hot select¶

Write a 1M-iteration loop that selects on ctx.Done() and time.After(time.Second). Profile the allocations. Replace time.After with a reused *time.Timer.

E7. Build a thundering-herd-safe deadline gate¶

Many goroutines wait for a deadline shared across them. Use a single AfterFunc (or context.AfterFunc) plus a sync.Cond or close-of-channel. Verify no spurious wakeups.

E8. Profile a real service¶

Pick any Go service you maintain. Look at the goroutine profile. Count time.Sleep and time.After waits. Identify two that could be AfterFunc instead.

E9. Implement context.AfterFunc from scratch¶

Using only time.AfterFunc and ctx.Done(), build your own version. Compare your implementation's API and behaviour to the standard library's.

E10. Test deterministically¶

Take any of the patterns from middle.md (debouncer, watchdog, idle conn) and rewrite to inject a clock interface. Write tests that drive the clock manually.

Senior-Level Tricky Questions¶

SQ1. Where does a timer live in memory after AfterFunc returns?

A. On the heap. The time.Timer struct is heap-allocated; the runtime holds a reference; user code may hold the returned pointer.

SQ2. Does the timer migrate between P's?

A. Normally no; it stays on the heap of the P that called AfterFunc. If that P is destroyed (GOMAXPROCS reduction), it migrates.

SQ3. What is the lock granularity for timer operations?

A. Per-P. Each P's timer heap has its own lock. This is why timer ops are cheap — no global contention.

SQ4. Does the runtime ever spawn a callback goroutine without using a go statement?

A. Effectively yes — the runtime has internal newproc-like calls that bypass the user-facing go keyword. Same goroutine result; different code path.

SQ5. Why isn't there a "wait for callback" API?

A. Three reasons: (1) most callbacks are idempotent and don't need it. (2) Adding it would require a Cond or channel on every timer, inflating memory. (3) Users who need it can build it cheaply with a channel.

SQ6. Why was the pre-1.23 timer state machine so complex?

A. It evolved organically as bugs were fixed. Each new edge case added a state. Go 1.23 finally consolidated.

SQ7. How does the runtime handle AfterFunc(d, f) where d is very large (e.g. 100 years)?

A. Just like any other duration. The heap entry has a huge when. It sits there forever until you Stop or the program exits.

SQ8. What is the maximum representable duration?

A. math.MaxInt64 nanoseconds, about 292 years.

SQ9. Can the runtime fire a timer before its when?

A. No, never. when is the earliest moment.

SQ10. How does Go choose which P to fire a timer on?

A. Whichever P notices the expired entry first (and they only check their own heap). Effectively, the P that owns the heap.

SQ11. What happens if GOMAXPROCS is set to 1?

A. One P, one timer heap, one place where timer firing happens. Single-threaded behaviour. Timer accuracy is fine but timers fire on the same OS thread as everything else, so a busy main goroutine can starve them slightly.

SQ12. Does runtime.LockOSThread() affect timer firing?

A. Timers fire on the P, which can be on any OS thread. LockOSThread pins a goroutine to a thread, but timers can still fire on other threads (and their callbacks spawn fresh goroutines, which can run anywhere).

SQ13. What is the relationship between sysmon and timers?

A. Sysmon is a fallback path: if a P is stuck (in a long syscall, or compute without preemption), sysmon notices and either steals work or fires timers itself.

SQ14. Why doesn't the runtime use a kernel timer (timerfd, kevent)?

A. Because Go has its own scheduler. A kernel timer would deliver to one OS thread, which would have to dispatch — adding latency and complicating multiplexing. Go uses the kernel only for epoll/kqueue-style polling with a timeout.

SQ15. Can a timer with period > 0 be created from user code?

A. Only via time.NewTicker. AfterFunc and NewTimer both create one-shot (period=0) timers.

SQ16. Why is t.C nil for an AfterFunc timer?

A. Because the runtime, at fire time, takes a different path: spawn a goroutine to run f, do not send on C. The time.Timer struct is shared with channel-style timers, but the C field is unused.

SQ17. Is the timer's when updated on Reset?

A. Yes. Reset(d) sets when = now + d and re-inserts into the heap.

SQ18. Why doesn't AfterFunc accept a context.Context?

A. Backwards compat — the API predates context.Context. The modern replacement is to combine time.AfterFunc with context.AfterFunc, or use one of them depending on the trigger.

SQ19. Does the runtime check timers on every scheduler iteration?

A. No, only when necessary — typically when a goroutine blocks, a goroutine completes, or sysmon notices. The exact policy varies by Go version.

SQ20. How does the timer interact with goroutine preemption?

A. A long-running callback is preempted like any goroutine. The async preemption (Go 1.14+) ensures it doesn't block the P forever. The timer itself is not affected — once fired, the runtime is done with it.

Cheat Sheet¶

// Architecture
// - Each P has a local min-heap of timers, keyed on `when` (monotonic ns).
// - The runtime checks heaps during scheduler iterations.
// - At fire time: pop, mark fired, spawn a goroutine to run f.
// - Stop, Reset are O(log n) heap ops; non-blocking on user code.

// Cost model (rough)
// - One timer: ~150 bytes (runtimeTimer + closure header).
// - Goroutine spawn on fire: a few hundred ns.
// - Heap insert/delete: O(log n), <100 ns at moderate n.

// Patterns by scale
// - <10K timers: per-entry timer, no issue.
// - 10K-100K: profile; consider reuse via Reset.
// - 100K-1M: batch into buckets or earliest-deadline scheduler.
// - >1M: hashed timing wheel or pivot architecture.

// Profiling
// - CPU: look for runtime.siftdownTimer, runtime.checkTimers.
// - Heap: look for runtimeTimer in allocations.
// - Goroutines: look for goroutines stuck in time.Sleep / <-time.After.

// Go version timeline
// - 1.10: monotonic clock; timers no longer affected by wall-clock jumps.
// - 1.14: async preemption.
// - 1.18: internal timer rewrite.
// - 1.21: context.AfterFunc.
// - 1.23: timer simplification; no Reset drain dance for NewTimer.
// - 1.24: testing/synctest.

Self-Assessment¶

• I can describe runtimeTimer's key fields.
• I can describe the P-local heap and how a timer lands on it.
• I can describe the path from heap pop to callback execution.
• I can explain what Stop and Reset do at the heap level.
• I can name the pre-1.23 state machine and explain why it simplified.
• I can estimate the cost of 100K vs 1M timers.
• I can name three batching strategies and when to use each.
• I can use pprof to identify timer-related cost.
• I know what changed in Go 1.10, 1.14, 1.21, 1.23.
• I can explain why t.C is nil for AfterFunc.

Summary¶

The senior view of AfterFunc:

• A time.Timer is a wrapper around a runtimeTimer that lives in a P-local min-heap, keyed on monotonic when.
• The runtime checks heaps during scheduler iterations; expired AfterFunc timers spawn a callback goroutine.
• Stop and Reset are O(log n) heap operations; they do not block on the callback.
• Pre-1.23 had a complex state machine; 1.23 simplified it. User-visible behaviour is unchanged.
• At scale (>100K timers), the per-timer cost and the spawn burst matter. Use batching strategies.
• Profile with pprof: CPU, heap, and goroutine profiles all illuminate timer behaviour.

The professional level moves from "how does it work" to "how do we run this in production at scale": observability, alerting, postmortems, incident response.

Further Reading¶

• Go source: runtime/time.go.
• Russ Cox, "Go's scheduler" talks and write-ups.
• Varghese & Lauck (1996), "Hashed and Hierarchical Timing Wheels."
• LKML threads on timer_list and related kernel structures (deeper than you need, but illuminating).
• The golang/go issue tracker — search for "timer" — many design discussions are public.

Diagrams¶

P-local heap¶

P0:               P1:               P2:               P3:
[t@+10ms]         [t@+50ms]         [t@+5ms ]         [t@+1s  ]
[t@+200ms]        [t@+1s  ]         [t@+800ms]        [t@+10s ]
[t@+5s   ]        [t@+30s ]

Each P checks only its own heap. No cross-P traffic for timer ops.

Fire path¶

scheduler picks next work
        |
        v
check P's timer heap
        |
        v
peek min -- is when <= now? -- no --> continue scheduler loop
        | yes
        v
pop min
        |
        v
mark fired in runtime
        |
        v
spawn goroutine (wrapper) --> wrapper does `go userFunc()` --> user code

Stop's effect¶

heap before:     [t1@+10ms, t2@+50ms, t3@+100ms]
                                ^
                                |
                              Stop(t2)
heap after:      [t1@+10ms, t3@+100ms]
return value: true (t2 was active)

Reset's effect on active timer¶

heap before:     [t1@+10ms (this), t2@+50ms]
                  ^
                  | Reset(100ms)
heap after:      [t2@+50ms, t1@+100ms]
return value: true (t1 was active)

Goroutine spawn flow¶

P0 thread:  ... scheduler iter ... pop timer ... newproc(wrapper) ... continue ...
P0 run q:                                                + wrapper goroutine
                                                                |
                                                                v
                                                       runs `go userFunc()`
                                                                |
                                                                v
                                                       userFunc goroutine on P0 or another P

Appendix A: Reading runtime/time.go in 30 minutes¶

Setup¶

cd $(go env GOROOT)/src/runtime
ls -la time.go

Open time.go in your editor.

Map of the file¶

The file is roughly organised:

1. type timer struct — the runtime's per-timer struct.
2. addtimer(t *timer) — insert a fresh timer into the calling P's heap.
3. deltimer(t *timer) bool — mark a timer for removal.
4. modtimer(t *timer, ...) bool — change when, used by Reset.
5. adjusttimers(pp *p) — clean up the heap.
6. runtimer(pp *p, now int64) int64 — run any expired timers, return when to check next.
7. siftupTimer/siftdownTimer — heap operations.

Sequence to trace¶

Trace time.AfterFunc from user code:

1. time.AfterFunc(d, f) in time/sleep.go calls startTimer(t).
2. startTimer (also in time/sleep.go) calls into the runtime via runtime.addtimer.
3. runtime.addtimer (in runtime/time.go) acquires the local P's timer lock, inserts into the heap, releases.

Now trace a fire:

1. The scheduler eventually calls checkTimers(pp, now).
2. checkTimers calls runtimer.
3. runtimer peeks the heap; if min is expired, it pops, marks the timer fired, and calls f(arg, 0).
4. For an AfterFunc, f is goFunc (in time/sleep.go), which does go arg.(func())().
5. The user's callback runs on the new goroutine.

That is the entire path.

Useful runtime helpers¶

• runtime.nanotime() — current monotonic time in nanoseconds.
• runtime.systemstack(...) — run a function on the system stack (used for some scheduler ops).
• mp / pp / gp — pointers to the current M, P, and G.

You do not need to understand all of these to follow the timer path.

Appendix B: Pre-1.23 status state machine, in detail¶

The states¶

timerNoStatus       0  // never used (timer not on a heap)
timerWaiting        1  // active on a heap
timerRunning        2  // f is being called
timerDeleted        3  // marked deleted; in heap until cleaned
timerRemoving       4  // someone is removing it
timerRemoved        5  // off the heap
timerModifying      6  // someone is modifying
timerModifiedEarlier 7 // when modified to a smaller value
timerModifiedLater   8 // when modified to a larger value
timerMoving         9  // being moved between P's

Why so many?¶

The complexity came from lock-free transitions. Multiple goroutines can call Stop, Reset, and the timer can simultaneously be firing. The runtime used CAS on the status to avoid contention. Each combination of "what's the current status?" and "what op is being attempted?" needed careful handling.

Common transitions¶

NoStatus --(addtimer)--> Waiting
Waiting --(fire)--> Running --> NoStatus or Modified or Removed
Waiting --(deltimer)--> Deleted --(cleanup)--> Removed
Waiting --(modtimer earlier)--> ModifiedEarlier
Waiting --(modtimer later)--> ModifiedLater

Post-1.23¶

The state machine effectively collapses to "active or not." Stop and Reset are implemented in terms of simpler primitives (addtimer, deltimer, modtimer) without the elaborate intermediate states.

The user-visible API is unchanged. The boolean returns mean the same thing.

Appendix C: A back-of-envelope cost model¶

Let:

• T = number of live timers.
• R = timer creations per second (rate).
• F = timer fires per second.
• S = timer stops per second.

Memory: M ≈ T × (120 bytes timer + capture size). For T = 1e6, capture size = 100 bytes: M ≈ 220 MB.

CPU (heap operations): each create/stop/reset is O(log T). At T = 1e6, log T ≈ 20. Each op is on the order of 100 ns. So CPU ≈ (R + S + F) × 100ns × log T. For R+S+F = 100K/sec, T = 1e6: CPU ≈ 100K × 100ns × 20 = 200ms/sec of CPU = 20% of one core.

Goroutine spawns at fire: goroutine_spawns_per_sec = F. Each spawn is ~300 ns. For F = 10K/sec: 0.003 sec/sec of CPU = 0.3% of one core. Cheap.

GC: with T = 1e6 and 100-byte captures, retained heap from timers is ~220 MB. The GC pause time scales with live heap, but typical pauses stay below 1 ms with Go's concurrent collector.

Practical takeaways¶

• Memory is the dominant cost at scale. Closure capture size matters.
• CPU is mostly heap operations. At T < 1e5 it is invisible. At T > 1e6 it is several percent.
• Goroutine spawns are usually a non-issue.

Appendix D: How to read a CPU profile for timer cost¶

After running pprof on a CPU profile:

(pprof) top10
Showing nodes accounting for 1.55s, 31.0% of 5s total
      flat  flat%   sum%        cum   cum%
     0.40s  8.00%  8.00%      0.60s 12.00%  runtime.siftdownTimer
     0.30s  6.00% 14.00%      0.40s  8.00%  runtime.siftupTimer
     0.25s  5.00% 19.00%      0.55s 11.00%  runtime.addtimer
     0.20s  4.00% 23.00%      0.30s  6.00%  runtime.deltimer
     0.15s  3.00% 26.00%      0.20s  4.00%  runtime.checkTimers
     ...

Interpretation: 30% of CPU is timer-related. Likely indicates either too many timers, or high churn rate. Investigate via heap and goroutine profiles.

What to do¶

• Reduce the count: batch into bucket timers.
• Reduce the churn: use Reset instead of Stop+AfterFunc.
• Move to a different structure: hashed timing wheel, earliest-deadline scheduler.

Appendix E: Walking through addtimer (simplified pseudocode)¶

func addtimer(t *timer) {
    // 1. Take a snapshot of "now" once.
    now := nanotime()

    // 2. Find the local P.
    pp := getg().m.p.ptr()

    // 3. Lock the P's timer-heap.
    lock(&pp.timersLock)

    // 4. Insert at end of heap, then sift up.
    pp.timers = append(pp.timers, t)
    siftupTimer(pp.timers, len(pp.timers)-1)

    // 5. Update accounting.
    pp.numTimers.Add(1)

    // 6. Wake up the netpoller if this timer is sooner than the next wake.
    if t.when < pp.timer0When.Load() {
        pp.timer0When.Store(t.when)
        wakeNetPoller(t.when)
    }

    unlock(&pp.timersLock)
}

Real code has more bells and whistles (the status field, race detector hooks, debug counters) but the structure is the same.

Why wake the netpoller?¶

If the P is parked in epoll_wait (or equivalent) with a longer timeout, the newly-inserted timer might fire before the wait would otherwise return. So the runtime sends a wakeup so the poll returns and the timer can be checked.

Appendix F: Walking through runtimer (simplified)¶

// Called by the scheduler to fire any expired timers on pp.
// Returns the next timer's when, or 0 if no more timers.
func runtimer(pp *p, now int64) int64 {
    for {
        if len(pp.timers) == 0 {
            return 0
        }
        t := pp.timers[0]
        if t.when > now {
            return t.when
        }
        // t expired.
        if t.period > 0 {
            // Repeating timer (Ticker). Advance and sift.
            t.when += t.period
            siftdownTimer(pp.timers, 0)
        } else {
            // One-shot. Remove from heap.
            removeFromTopOfHeap(pp.timers)
        }

        // Call the timer's f. For AfterFunc, this is goFunc which does `go userFunc()`.
        f := t.f
        arg := t.arg
        unlock(&pp.timersLock)
        f(arg, t.seq)
        lock(&pp.timersLock)
    }
}

The function fires all expired timers in one pass, then returns the next wake-time. The scheduler can use that to set its next poll timeout.

Appendix G: A self-contained latency experiment¶

package main

import (
    "fmt"
    "sort"
    "time"
)

func main() {
    const N = 10_000
    target := 100 * time.Millisecond
    lateness := make([]time.Duration, 0, N)
    done := make(chan struct{}, N)

    start := time.Now()
    for i := 0; i < N; i++ {
        scheduledFor := start.Add(target)
        time.AfterFunc(target, func() {
            late := time.Since(scheduledFor)
            lateness = append(lateness, late)
            done <- struct{}{}
        })
    }

    for i := 0; i < N; i++ {
        <-done
    }

    sort.Slice(lateness, func(i, j int) bool { return lateness[i] < lateness[j] })
    fmt.Println("p50:", lateness[N/2])
    fmt.Println("p99:", lateness[N*99/100])
    fmt.Println("p999:", lateness[N*999/1000])
    fmt.Println("max:", lateness[N-1])
}

Run this. On a modest laptop you should see p50 around 100 µs of lateness, p99 around 1 ms, and max possibly in the 10–50 ms range. The p99 is the number you should plan around.

Note: the lateness slice is unsynchronised; multiple callbacks append concurrently. Add a mutex or use sync/atomic for production-quality measurement.

Appendix H: Architectural lessons¶

A few high-level lessons accumulate after working with AfterFunc at scale.

1. Memory is the first scaling wall. Closure capture multiplied by timer count is your budget. Audit captures.
2. Throughput is the second wall. O(log n) heap operations are fast but not free. Million-timer services need batching.
3. Goroutine spawns are usually not the wall. Even at 100K fires per second, the spawn cost is sub-second of CPU.
4. Test with mock clocks. Real-time tests are flaky. A clock interface pays for itself.
5. context.AfterFunc is your friend. For context-driven cleanup, prefer it.
6. Observability matters. Export a metric for "live timer count" via your own bookkeeping. The runtime doesn't.
7. Don't reinvent timing wheels at small scale. The standard heap is good up to 100K. Reach for fancier structures only when you have profile data showing it matters.

Appendix I: Senior FAQ¶

Q. Why does Go not provide a time.AfterFuncContext(ctx, d, f) that combines both triggers?

A. Composability. time.AfterFunc(d, f) and context.AfterFunc(ctx, cancel) can be combined by user code. Adding more API surface for every combination would be unwieldy.

Q. What is the smallest practical duration?

A. Effectively the scheduler's minimum poll interval, which is in the microseconds range. time.AfterFunc(1*time.Nanosecond, f) will fire almost immediately, but with some jitter.

Q. Can I influence which P my timer joins?

A. Indirectly, via runtime.LockOSThread — but you cannot pin a goroutine to a P in user code. The runtime decides.

Q. What is the precision of time.Duration?

A. Nanoseconds. The runtime uses nanoseconds end to end.

Q. Why does my callback fire late under GC?

A. During a GC stop-the-world pause (typically < 1 ms), no goroutines run, so callbacks can't fire. The pause is short but visible if you measure carefully.

Q. Why does my callback fire late under heavy CPU load?

A. All P's are busy with goroutines; timer checks happen at scheduler iterations and may be delayed. Async preemption (Go 1.14+) helps but doesn't eliminate it.

Q. Can I run timer callbacks on a dedicated goroutine pool?

A. Not directly. You can have the callback push work to a pool: time.AfterFunc(d, func() { pool.Submit(actualWork) }).

Q. Is time.AfterFunc slower on Windows / macOS than Linux?

A. Marginally. The underlying syscall for net polling differs (epoll vs kqueue vs IOCP). For modest timer counts, you won't notice.

Q. Does GOMAXPROCS affect timer accuracy?

A. Yes. With GOMAXPROCS=1, all timers fire on one P; if that P is busy, timers wait. Higher GOMAXPROCS distributes timer firing across P's.

Q. Is time.AfterFunc safe in test goroutines that the test framework may kill?

A. Yes — the test goroutine and timer callback are independent. But the callback may run after the test ends if you don't Stop it; clean up properly.

Appendix J: A list of bugs the runtime team fixed over the years¶

For motivation, here are some real timer-related bugs from the Go issue tracker:

• #6452 (early): timer leak after Stop.
• #17448: data race in concurrent Reset.
• #25686: Reset returning incorrect value in some race.
• #32834: timer not firing on heavily loaded systems.
• #34025: time.Sleep and timer interactions.
• #50059: Reset semantics ambiguity prompting documentation rewrite.
• #60665: Go 1.21 context.AfterFunc proposal and implementation.
• #62410: Go 1.23 timer simplification.

You don't need to read each, but skimming the discussions gives a sense of the complexity hidden in time.AfterFunc. The current API is the product of decades of refinement.

Appendix K: Performance comparison table¶

Approximate numbers, modern CPU, GOMAXPROCS=8:

These are not authoritative benchmarks — your hardware, Go version, and workload will produce different numbers. Run your own.

Appendix L: Annotated source tour of runtime/time.go¶

Below is a guided tour of the most relevant function bodies in the Go runtime, paraphrased and annotated. Numbers refer to a stylised reading of the source for Go 1.23+, not the literal line numbers (which change between releases). Use this as scaffolding for your own reading.

L.1 — The timer struct¶

The runtime's representation of a timer is, conceptually:

type timer struct {
    // Heap position. Negative if not in any heap.
    mu        mutex      // guards a few fields
    astate    atomic.Uint8 // active status flags
    state     uint8      // additional state flags
    isChan    bool       // distinguishes channel-style from AfterFunc-style

    blocked   uint32     // count of blocked sends in transitional state

    sendLock  mutex      // serialises channel sends for ticker

    // The user-visible fields (mirror of time.Timer's runtimeTimer view):
    when      int64      // monotonic nanoseconds
    period    int64      // 0 for AfterFunc; > 0 for Ticker
    f         func(any, uintptr)
    arg       any
    seq       uintptr
}

What to notice:

• mu is a runtime mutex, not a sync.Mutex. Runtime mutexes are lighter-weight and not visible to the race detector in the same way.
• astate is an atomic byte used for lock-free transitions.
• isChan selects between "send on a channel at fire" and "spawn goroutine running f at fire."
• The wrapper for AfterFunc has isChan = false and a wrapper f that spawns a goroutine.

L.2 — addtimer, the "create-and-arm" path¶

In the standard library:

// time/sleep.go
func AfterFunc(d Duration, f func()) *Timer {
    t := &Timer{
        r: runtimeTimer{
            when: when(d),
            f:    goFunc,
            arg:  f,
        },
    }
    startTimer(&t.r)
    return t
}

startTimer calls into the runtime via a linkname:

// runtime/time.go
//go:linkname startTimer time.startTimer
func startTimer(t *timer) {
    // ... defensive checks ...
    t.mu.Lock()
    t.maybeRunChan()
    addtimer(t)
    t.mu.Unlock()
}

Then addtimer proper:

func addtimer(t *timer) {
    if t.when <= 0 {
        // Negative or zero duration: fire ASAP.
        t.when = nanotime()
    }

    pp := getg().m.p.ptr()
    pp.timers.lock.Lock()

    // Insert into heap.
    t.ph = len(pp.timers.heap)
    pp.timers.heap = append(pp.timers.heap, t)
    siftupTimer(pp.timers.heap, t.ph)
    pp.timers.added.Add(1)

    pp.timers.updateMinNextWhen(t.when)

    pp.timers.lock.Unlock()

    if t.when < pp.timer0When.Load() {
        wakeNetPoller(t.when)
    }
}

What to notice:

• pp is the current P. Insertion is into the local P's heap.
• After insertion, the runtime may need to wake the netpoller if this timer fires before the netpoller's current timeout.

L.3 — runtimer, the "fire expired timers" path¶

// Called by the scheduler from various places.
func runtimer(pp *p, now int64) int64 {
    pp.timers.lock.Lock()
    for {
        if len(pp.timers.heap) == 0 {
            pp.timers.lock.Unlock()
            return -1
        }
        t := pp.timers.heap[0]
        if t.when > now {
            // No expired timer yet; report when to check next.
            next := t.when
            pp.timers.lock.Unlock()
            return next
        }

        // Pop the timer.
        if t.period > 0 {
            // Repeating: advance when, sift down.
            t.when += t.period
            siftdownTimer(pp.timers.heap, 0)
        } else {
            // One-shot: remove from heap.
            removeFromTopOfHeap(pp.timers.heap)
            t.ph = -1
        }

        f := t.f
        arg := t.arg
        seq := t.seq

        // Release the lock before calling f. f may do anything,
        // including modify timers — must not hold the lock.
        pp.timers.lock.Unlock()
        f(arg, seq)
        pp.timers.lock.Lock()
    }
}

What to notice:

• The lock is released before f is called. This is critical — f may itself call into timer code, and holding the lock would deadlock.
• f is the wrapper. For AfterFunc it does go arg.(func())(). For Ticker it does the channel send.
• Repeating timers (Tickers) are not removed but re-sifted with an advanced when.

L.4 — goFunc, the AfterFunc wrapper¶

// time/sleep.go
func goFunc(arg any, seq uintptr) {
    go arg.(func())()
}

That's the whole wrapper. The runtime invokes it with arg = user's f. go arg.(func())() spawns a fresh goroutine to run the user's callback.

Why a wrapper? Because the runtime's f signature is func(any, uintptr). The user's f is func(). The wrapper bridges the type difference and provides the go (which is why callbacks run on a new goroutine).

L.5 — deltimer, the "mark for removal" path¶

func deltimer(t *timer) bool {
    if t.ph < 0 {
        // Already removed.
        return false
    }
    pp := t.pp
    pp.timers.lock.Lock()
    if t.ph >= 0 && pp.timers.heap[t.ph] == t {
        removeFromHeap(pp.timers.heap, t.ph)
        t.ph = -1
        pp.timers.deleted.Add(1)
        pp.timers.lock.Unlock()
        return true
    }
    pp.timers.lock.Unlock()
    return false
}

This is simplified. The real implementation handles:

• Timers being moved between P's.
• Concurrent modifications (modtimer racing with deltimer).
• The case where the timer is currently being processed by runtimer on another P.

L.6 — modtimer, the Reset path¶

func modtimer(t *timer, when, period int64, f func(any, uintptr), arg any, seq uintptr) bool {
    pp := getg().m.p.ptr()
    pp.timers.lock.Lock()

    wasActive := false
    if t.ph >= 0 && pp.timers.heap[t.ph] == t {
        // Active: remove from heap, will reinsert.
        removeFromHeap(pp.timers.heap, t.ph)
        wasActive = true
    }

    t.when = when
    t.period = period
    if f != nil {
        t.f = f
        t.arg = arg
        t.seq = seq
    }

    // Insert into heap.
    t.ph = len(pp.timers.heap)
    pp.timers.heap = append(pp.timers.heap, t)
    siftupTimer(pp.timers.heap, t.ph)

    pp.timers.updateMinNextWhen(t.when)
    pp.timers.lock.Unlock()

    if t.when < pp.timer0When.Load() {
        wakeNetPoller(t.when)
    }
    return wasActive
}

Reset calls modtimer (via resetTimer) with the new when, the same f/arg/seq. The boolean return is wasActive.

For AfterFunc, the user-facing Reset(d) translates to modtimer(t, now+d, 0, nil, nil, 0) — no change to f or arg.

L.7 — Heap operations¶

siftupTimer and siftdownTimer are min-heap operations on a slice of *timer, keyed on when. The implementation is a standard 4-ary heap (the original Go heap used 4-ary for cache friendliness, although the multiplier has varied between versions).

func siftupTimer(t []*timer, i int) {
    when := t[i].when
    tmp := t[i]
    for i > 0 {
        p := (i - 1) / 4 // 4-ary parent
        if when >= t[p].when {
            break
        }
        t[i] = t[p]
        t[i].ph = i
        i = p
    }
    if tmp != t[i] {
        t[i] = tmp
        t[i].ph = i
    }
}

Each element knows its position via ph, so deletion is O(log n) (find by index, sift down or up).

Appendix M: A detailed cost model for batching¶

Suppose you have N entries each with a deadline. Three strategies:

Strategy A: one timer per entry¶

• N timers in the runtime heap.
• Insert: O(log N) per entry; total O(N log N) for the initial load.
• Fire: each entry fires its own timer; total O(N log N) heap operations spread over time.
• Memory: N × (timer + closure) ≈ N × 200 bytes.

For N = 1e6: 200 MB memory; CPU cost negligible if fires are spread over hours.

Strategy B: earliest-deadline scheduler¶

• 1 timer at any time (for the earliest deadline).
• User maintains a min-heap of entries (separately from the runtime's heap).
• Insert into user heap: O(log N). If the new entry is now the earliest, also call Reset on the runtime timer (one heap op).
• Fire: process all entries that are due, then Reset for the next earliest.
• Memory: N × entry size + 1 timer ≈ N × 100 bytes + 200 bytes.

For N = 1e6: 100 MB memory; CPU cost dominated by the user heap, not the runtime timer.

Strategy C: bucketed (timing wheel)¶

• B buckets, each with a list of entries.
• Insert: O(1) — append to the appropriate bucket's list.
• Fire: every "tick" the runtime fires one timer; the callback processes the bucket's list.
• Memory: B + total entries.
• Accuracy: 1 tick width (e.g., 100 ms). Not suitable for sub-tick deadlines.

For N = 1e6, B = 1000 buckets at 100 ms each: 1000 active timers, O(1) inserts, sub-100ms fire latency.

Choosing¶

For most production services, B is the sweet spot.

Appendix N: Implementing the earliest-deadline scheduler¶

A reference implementation, with comments.

package edscheduler

import (
    "container/heap"
    "sync"
    "time"
)

type Entry struct {
    Deadline time.Time
    Handler  func()
    index    int // heap index
}

type entryHeap []*Entry

func (h entryHeap) Len() int { return len(h) }
func (h entryHeap) Less(i, j int) bool { return h[i].Deadline.Before(h[j].Deadline) }
func (h entryHeap) Swap(i, j int) {
    h[i], h[j] = h[j], h[i]
    h[i].index = i
    h[j].index = j
}
func (h *entryHeap) Push(x interface{}) {
    e := x.(*Entry)
    e.index = len(*h)
    *h = append(*h, e)
}
func (h *entryHeap) Pop() interface{} {
    n := len(*h)
    e := (*h)[n-1]
    e.index = -1
    *h = (*h)[:n-1]
    return e
}

type Scheduler struct {
    mu      sync.Mutex
    entries entryHeap
    timer   *time.Timer
}

func New() *Scheduler {
    return &Scheduler{}
}

func (s *Scheduler) Schedule(e *Entry) {
    s.mu.Lock()
    defer s.mu.Unlock()
    heap.Push(&s.entries, e)
    s.armLocked()
}

func (s *Scheduler) Cancel(e *Entry) bool {
    s.mu.Lock()
    defer s.mu.Unlock()
    if e.index < 0 {
        return false
    }
    heap.Remove(&s.entries, e.index)
    s.armLocked()
    return true
}

func (s *Scheduler) armLocked() {
    if s.entries.Len() == 0 {
        if s.timer != nil {
            s.timer.Stop()
        }
        return
    }
    d := time.Until(s.entries[0].Deadline)
    if d < 0 {
        d = 0
    }
    if s.timer == nil {
        s.timer = time.AfterFunc(d, s.fire)
    } else {
        s.timer.Reset(d)
    }
}

func (s *Scheduler) fire() {
    s.mu.Lock()
    now := time.Now()
    var due []*Entry
    for s.entries.Len() > 0 && !s.entries[0].Deadline.After(now) {
        e := heap.Pop(&s.entries).(*Entry)
        due = append(due, e)
    }
    s.armLocked()
    s.mu.Unlock()
    for _, e := range due {
        e.Handler() // run on this goroutine, in deadline order
    }
}

Performance:

• Schedule: O(log N) for heap insertion + O(1) for the Reset (if needed).
• Cancel: O(log N) for heap removal.
• fire: O(k log N) where k = entries due. Amortised O(log N) per entry over time.

At N = 1e6, all operations are sub-microsecond.

When to use this¶

• N > 100K timers.
• Entries have precise deadlines.
• You want a single goroutine spawn (per fire batch) instead of one per entry.

When not to use this¶

• N < 10K — per-entry timers are simpler.
• Entries are short-lived; the rebalancing cost dominates.
• Cancellation rate is very high; the user heap's O(log N) removal piles up.

Appendix O: Implementing a hashed timing wheel¶

A simple single-level hashed timing wheel.

package wheel

import (
    "sync"
    "time"
)

type Entry struct {
    Handler func()
    // Internal:
    bucket int
    next   *Entry
    prev   *Entry
}

type Wheel struct {
    mu       sync.Mutex
    tickSize time.Duration
    buckets  []*Entry // each bucket is a doubly linked list head
    cursor   int
    timer    *time.Timer
    start    time.Time
}

func New(tickSize time.Duration, numBuckets int) *Wheel {
    w := &Wheel{
        tickSize: tickSize,
        buckets:  make([]*Entry, numBuckets),
        start:    time.Now(),
    }
    w.timer = time.AfterFunc(tickSize, w.tick)
    return w
}

func (w *Wheel) Schedule(after time.Duration, fn func()) *Entry {
    w.mu.Lock()
    defer w.mu.Unlock()
    bucketsAhead := int(after / w.tickSize)
    if bucketsAhead < 1 {
        bucketsAhead = 1
    }
    idx := (w.cursor + bucketsAhead) % len(w.buckets)
    e := &Entry{Handler: fn, bucket: idx}

    // Push to head of linked list.
    e.next = w.buckets[idx]
    if w.buckets[idx] != nil {
        w.buckets[idx].prev = e
    }
    w.buckets[idx] = e
    return e
}

func (w *Wheel) Cancel(e *Entry) {
    w.mu.Lock()
    defer w.mu.Unlock()
    if e.bucket < 0 {
        return
    }
    if e.prev != nil {
        e.prev.next = e.next
    } else {
        w.buckets[e.bucket] = e.next
    }
    if e.next != nil {
        e.next.prev = e.prev
    }
    e.bucket = -1
}

func (w *Wheel) tick() {
    w.mu.Lock()
    head := w.buckets[w.cursor]
    w.buckets[w.cursor] = nil
    w.cursor = (w.cursor + 1) % len(w.buckets)
    w.mu.Unlock()

    // Process the bucket.
    for e := head; e != nil; e = e.next {
        e.bucket = -1 // mark removed (don't accidentally cancel during run)
        e.Handler()
    }

    // Re-arm.
    w.timer.Reset(w.tickSize)
}

Properties:

• O(1) Schedule and Cancel.
• Accuracy: ±1 tick.
• Memory: O(buckets + entries).
• Maximum delay: tickSize × numBuckets (entries beyond this need a hierarchical wheel).

This is suitable for very high-cardinality scenarios (millions of entries with similar deadlines) where the standard heap's O(log N) is felt.

Caveats¶

• The tick callback runs the handlers in the same goroutine. If a handler is slow, subsequent ticks are delayed. Consider dispatching to a worker pool.
• Cancellation requires the *Entry token. Plan your application to track these.

Appendix P: When timer behaviour matters for correctness¶

For some applications, timer accuracy is part of the correctness contract:

Distributed systems heartbeats¶

A node sends a heartbeat every d. Another node times out the connection after 2d of silence. If timer accuracy is poor, false positives ("node down") occur.

Mitigations:

• Use generous timeout (e.g. 5d for "d-period" heartbeats).
• Use multiple timers (e.g., "missed 3 heartbeats in a row").
• Use the difference between successful heartbeat receipts, not just elapsed time.

Rate limiters¶

A leaky-bucket rate limiter refills tokens every d. If the timer is late, the bucket is under-filled and clients are throttled more than they should be.

Mitigations:

• Use computed-on-demand refill: when a request arrives, compute the elapsed time and add tokens, rather than relying on a fire.
• Use generous bucket size.

Distributed locks¶

A holder renews a lease every d; an observer assumes the lock is free after 2d. Same issue as heartbeats.

TLS handshake timeouts¶

If the timer fires later than expected, the handshake may succeed even when the application meant it to fail. This rarely matters for correctness, but it has been the root cause of bugs in mocking.

Game tick rates¶

A game server with a 60 Hz tick rate cannot afford 30 ms jitter. Use time.NewTicker (more accurate than self-rescheduling AfterFunc) and possibly OS-level high-resolution timers.

Appendix Q: Common antipatterns at the senior level¶

Antipattern 1: Custom timing wheel for 100 timers¶

You don't need it. The standard heap is faster and simpler at this scale. Custom data structures pay off only at high N.

Antipattern 2: One timer per byte of incoming data¶

I have seen designs where a TCP server creates an "idle timer" per packet, instead of per connection. This is millions of timers under load. Fix: one timer per connection, reset on each packet.

Antipattern 3: Misusing Reset's return value¶

if !t.Reset(d) {
    // Timer was not active; do something special?
}

For AfterFunc timers, this return is almost never useful. Don't gate logic on it.

Antipattern 4: Polling for timer fire¶

go func() {
    for !flag.Load() {
        time.Sleep(time.Millisecond)
    }
    // ... handle ...
}()
time.AfterFunc(d, func() { flag.Store(true) })

Spinning a polling goroutine defeats the point of timers. Use a channel:

done := make(chan struct{})
time.AfterFunc(d, func() { close(done) })
<-done

Antipattern 5: Storing timers in slices indexed by row ID¶

var timers [1_000_000]*time.Timer

The slice is permanent. Even if you Stop and nil-out entries, the slice itself is 8 MB. Use a map keyed by something meaningful.

Antipattern 6: Calling Reset every microsecond¶

Very high reset rates churn the heap. If you're resetting more than 100K times per second, batch.

Antipattern 7: Recursive AfterFunc without bound¶

var run func()
run = func() {
    time.AfterFunc(0, run)
}
run()

Infinite. Even with period = 0, the heap insertion + goroutine spawn cost adds up. The runtime will service this as fast as it can, but you have created a busy loop with extra overhead.

Appendix R: Verification — proving timer behaviour in tests¶

To verify a timer-based component is correct, set up scenarios and check invariants.

Scenario: deadline fires exactly once¶

func TestDeadlineFiresOnce(t *testing.T) {
    var calls atomic.Int64
    fn := func() { calls.Add(1) }
    d := NewDeadline(50*time.Millisecond, fn)
    _ = d
    time.Sleep(200 * time.Millisecond)
    if got := calls.Load(); got != 1 {
        t.Fatalf("expected 1 call, got %d", got)
    }
}

Scenario: cancel prevents fire¶

func TestCancelPrevents(t *testing.T) {
    var calls atomic.Int64
    d := NewDeadline(50*time.Millisecond, func() { calls.Add(1) })
    d.Cancel()
    time.Sleep(100 * time.Millisecond)
    if got := calls.Load(); got != 0 {
        t.Fatalf("expected 0 calls, got %d", got)
    }
}

Scenario: cancel after fire is harmless¶

func TestCancelAfterFire(t *testing.T) {
    var calls atomic.Int64
    d := NewDeadline(20*time.Millisecond, func() { calls.Add(1) })
    time.Sleep(50 * time.Millisecond)
    d.Cancel() // already fired; no effect
    if got := calls.Load(); got != 1 {
        t.Fatalf("expected 1 call, got %d", got)
    }
}

Scenario: stress test for races¶

func TestRace(t *testing.T) {
    for i := 0; i < 1000; i++ {
        var calls atomic.Int64
        d := NewDeadline(time.Millisecond, func() { calls.Add(1) })
        d.Cancel()
        time.Sleep(5 * time.Millisecond)
        if got := calls.Load(); got > 1 {
            t.Fatalf("got %d calls", got)
        }
    }
}

Run with -race. The detector catches any data race in the component's internals.

Property test¶

Use quick.Check to randomise the trigger / cancel ordering, asserting "at most one call":

quick.Check(func(t1, t2 time.Duration) bool {
    if t1 > time.Second || t2 > time.Second { return true } // skip
    var calls atomic.Int64
    d := NewDeadline(t1, func() { calls.Add(1) })
    time.AfterFunc(t2, d.Cancel)
    time.Sleep(2 * time.Second)
    return calls.Load() <= 1
}, nil)

Appendix S: A toy "runtime timer" implementation¶

Sometimes it helps to implement the data structures yourself, in user code, to see how they work.

package mytimer

import (
    "container/heap"
    "sync"
    "time"
)

type timer struct {
    when  time.Time
    f     func()
    index int // heap position
}

type timerHeap []*timer

func (h timerHeap) Len() int { return len(h) }
func (h timerHeap) Less(i, j int) bool { return h[i].when.Before(h[j].when) }
func (h timerHeap) Swap(i, j int) {
    h[i], h[j] = h[j], h[i]
    h[i].index = i
    h[j].index = j
}
func (h *timerHeap) Push(x interface{}) {
    t := x.(*timer)
    t.index = len(*h)
    *h = append(*h, t)
}
func (h *timerHeap) Pop() interface{} {
    n := len(*h)
    t := (*h)[n-1]
    t.index = -1
    *h = (*h)[:n-1]
    return t
}

type Runtime struct {
    mu      sync.Mutex
    h       timerHeap
    notify  chan struct{}
    stop    chan struct{}
    started bool
}

func (r *Runtime) AfterFunc(d time.Duration, f func()) *timer {
    r.mu.Lock()
    defer r.mu.Unlock()
    if !r.started {
        r.notify = make(chan struct{}, 1)
        r.stop = make(chan struct{})
        go r.loop()
        r.started = true
    }
    t := &timer{when: time.Now().Add(d), f: f}
    heap.Push(&r.h, t)
    select {
    case r.notify <- struct{}{}:
    default:
    }
    return t
}

func (r *Runtime) Stop(t *timer) bool {
    r.mu.Lock()
    defer r.mu.Unlock()
    if t.index < 0 {
        return false
    }
    heap.Remove(&r.h, t.index)
    return true
}

func (r *Runtime) loop() {
    for {
        r.mu.Lock()
        var d time.Duration
        if r.h.Len() == 0 {
            d = 24 * time.Hour
        } else {
            d = time.Until(r.h[0].when)
        }
        r.mu.Unlock()

        select {
        case <-time.After(d):
        case <-r.notify:
        case <-r.stop:
            return
        }

        r.mu.Lock()
        now := time.Now()
        for r.h.Len() > 0 && !r.h[0].when.After(now) {
            t := heap.Pop(&r.h).(*timer)
            f := t.f
            r.mu.Unlock()
            go f()
            r.mu.Lock()
        }
        r.mu.Unlock()
    }
}