Debounce and Throttle — Junior Level¶

Table of Contents¶

1. Introduction
2. Prerequisites
3. Glossary
4. Core Concepts
5. Real-World Analogies
6. Mental Models
7. Pros and Cons
8. Use Cases
9. Code Examples
10. Coding Patterns
11. Clean Code
12. Product Use and Feature
13. Error Handling
14. Security Considerations
15. Performance Tips
16. Best Practices
17. Edge Cases and Pitfalls
18. Common Mistakes
19. Common Misconceptions
20. Tricky Points
21. Test
22. Tricky Questions
23. Cheat Sheet
24. Self-Assessment Checklist
25. Summary
26. What You Can Build
27. Further Reading
28. Related Topics
29. Diagrams and Visual Aids

Introduction¶

Focus: "What is debounce? What is throttle? Why do I need either? How do I write the simplest version of each in Go?"

When events arrive in bursts, naive code processes every event the moment it arrives. Most of the time that is fine. Occasionally it is a disaster.

Suppose you wire a search box on a web page to a function that calls your server. The user types g, go, gol, gola, golan, golang. Without any safeguard your code fires six HTTP requests in under a second. Five of them are wasted because the user only really cares about the answer to the last query. The server now spends CPU cycles answering questions nobody is going to look at.

A debouncer fixes this. It says, "Wait until the user has stopped typing for, say, 300 milliseconds. Then send one request." The first five events are absorbed silently and the sixth, after the user pauses, finally fires.

Now suppose you write a logger that prints a line every time a database error occurs. The database goes down. Your code now generates ten thousand error log lines per second. Disk fills, the log shipper falls behind, the on-call engineer cannot read the screen because new errors push the useful ones off the top.

A throttler fixes this. It says, "No matter how many events you give me, I will only let one through every second." The first event fires immediately; the next 999 in that second are dropped or queued; the second after that, exactly one more fires.

Debounce waits for quiet. Throttle enforces a maximum rate. They sound similar and beginners regularly confuse them, but they are different patterns and you need both in your toolbox.

After reading this file you will:

• Be able to state the difference between debounce and throttle in one sentence
• Write a working debouncer using time.AfterFunc
• Write a working throttler using time.Ticker
• Know when each is the right tool
• Recognise the first four bugs every Go programmer hits when implementing them
• Understand why both patterns are about time-based concurrency, not just about plain rate limiting

We will not yet tackle leading-edge debounce, token buckets, sliding windows, distributed throttling, or any production concerns. Those live in middle.md, senior.md, and professional.md. The goal here is to build a rock-solid mental model and one working example of each pattern.

Prerequisites¶

You need to know:

• Channels: how to make one, send to one, receive from one, close one
• Goroutines: how to start one with go, what sync.WaitGroup is for
• select statements: how a select picks one of several ready channels
• time.Sleep, time.Duration, time.Now
• time.After, time.Ticker, time.AfterFunc: the basics from 01-ticker, 02-afterfunc, and 03-timer-leaks
• Basic concurrency safety with sync.Mutex

If any of those is fuzzy, read the earlier pages in the Concurrency track first. Debounce and throttle are applications of those primitives; you cannot understand the applications without the primitives.

You do not need to know:

• The golang.org/x/time/rate package yet — middle.md introduces it
• Leaky-bucket math — senior.md covers it
• Distributed rate limiting — senior.md and professional.md cover it
• The Go scheduler internals — irrelevant here

Glossary¶

Event: any discrete signal you want to handle — a keystroke, an HTTP request, a database write, a metric update, a button click, a log line. The "thing" arriving at the rate-limiter.

Burst: a cluster of events arriving close together in time, separated by gaps of relative quiet. Bursts are the entire reason debounce and throttle exist; if events were perfectly evenly spaced you would not need either tool.

Quiet period: a stretch of time with no events. A debouncer uses the quiet period to decide it is finally safe to fire.

Debounce: collapse a burst of events into a single trigger that fires only after the events stop. The trigger normally carries the last event's payload. Synonym: "tail collapse".

Trailing debounce: the default flavour described above — fire at the end of the burst.

Leading debounce: fire at the start of the burst; ignore all events until a quiet period passes. Less common but useful for "first click wins" UI buttons.

Leading + trailing debounce: fire on both the first and the last event of a burst. Useful when you want immediate feedback and a final reconcile.

Throttle: enforce a maximum frequency. Let an event through every N units of time and drop, queue, or block the rest.

Rate limit: a synonym for throttle in the wider engineering vocabulary. In Go the standard library uses the word "rate".

Token bucket: a throttle algorithm based on a bucket that holds up to B tokens and refills at R tokens per second. Each event removes a token; if the bucket is empty the event is dropped or waits.

Leaky bucket: a throttle algorithm shaped like a bucket with a hole. Events pour in at any rate; output drips out at a fixed rate. Compared to a token bucket it cannot burst.

Sliding window: a throttle that counts events in the last N seconds (or the last M milliseconds, etc.) and rejects new events once the count crosses a threshold.

time.Timer: a Go primitive that fires once after a duration. Can be reset.

time.Ticker: a Go primitive that fires repeatedly on an interval.

time.AfterFunc(d, f): convenience function that runs f in its own goroutine after d has elapsed. Returns a *time.Timer you can Reset or Stop.

Coalesce: combine multiple events into one — the action a debouncer performs.

Backpressure: any mechanism that makes a producer slow down because the consumer cannot keep up. Throttling is a form of backpressure when it blocks; it is a form of dropping when it does not.

Goroutine leak: a goroutine that never exits, usually because it is blocked on a channel that will never receive again. Debouncers and throttlers are surprisingly easy to leak; we will spend time on this.

Idempotent: an operation that has the same effect whether you run it once or a hundred times. Debouncing only makes sense for idempotent or "last-write-wins" operations, because earlier events are discarded.

Core Concepts¶

1. The fundamental distinction¶

The shortest definition you will ever need:

Debounce waits for silence. Throttle waits for the clock.

Read that twice. If you remember nothing else from this file, remember that.

Concretely, a debouncer is shaped like this:

event arrives → reset a countdown to T milliseconds
when countdown reaches zero → fire

A throttler is shaped like this:

event arrives → if the clock has ticked since last fire, fire; else drop/queue
clock ticks every T milliseconds

Notice that the debouncer's timer is reset every event and the throttler's timer is never reset. That single difference is the entire conceptual gap.

2. Why timers are not enough¶

A naive first attempt at "rate limiting" is to call time.Sleep between actions. It works in toy code:

for _, ev := range events {
    process(ev)
    time.Sleep(100 * time.Millisecond)
}

This is not throttling; it is pacing. The pacing version assumes events arrive on demand and you control the loop. Real systems have producers and consumers running on different goroutines. The producer does not want to block; it wants to fire events as fast as they come in. The consumer wants to enforce a rate. The bridge between them is a channel plus a select and a timer.

3. Why goroutines are mandatory¶

You cannot debounce or throttle "in place" inside a single function. The whole point of these patterns is that time passes between events. Something must hold state across calls — the time of the last event, the countdown to the next fire, the bucket of tokens. That state lives in a goroutine (with channels) or in a struct (with a mutex). Either way, time is a first-class participant in the design.

4. Why channels and select matter¶

A debouncer or throttler running in isolation is useless. It only earns its keep when wired into a pipeline that emits events and consumes results. The standard Go idiom for that wiring is:

• A chan T for input
• A chan T (or callback) for output
• A <-chan time.Time from a timer or ticker
• A select that watches all three

The select is where the real logic happens. It lets the goroutine wake up on whichever of "event arrived", "timer fired", or "context cancelled" happens first. Every debouncer and throttler in this whole subsection is some variation of that pattern.

5. Trailing-edge debounce: the default¶

When people say "debounce" without qualification they almost always mean trailing-edge. Events stretch out a timer; when the timer finally expires, the most recent event's payload is delivered.

events:   E E E       E   E E E
                      ↑
                  timer fires here, delivering the last E

The big advantages of trailing debounce are:

• Only ever one delivered event per burst, ever
• The delivered event carries the latest data (good for "save the document" or "send the search query")
• Cheap to implement with AfterFunc

The big disadvantage is latency. The user has to stop before the action happens. If your debounce window is 500ms, every action is delayed by 500ms. For a search-as-you-type box that is fine. For "user clicked Save" it is awful — by then they expect immediate feedback.

6. Leading-edge debounce¶

Sometimes you want the first event to fire and the rest to be ignored. The classic case is a button that submits a form. You want one submission, not five if the user clicks furiously. You want the first click to go through, and you want the rest to be silently swallowed until things settle down.

events:   E E E       E   E E E
          ↑           ↑
       fires here  fires here (after quiet gap)

We will not write the full leading version here — that is middle.md territory — but you should know it exists. Junior code often gets bug reports like "the button only submits when I stop clicking" because someone reached for trailing debounce when leading was the right tool.

7. Throttle: enforce a steady rhythm¶

A throttle does not care about quiet at all. It cares about the clock. Every T milliseconds, one event is allowed through. Extra events are either dropped (lossy throttle) or queued (lossless throttle, with bounded queue) or made to block (backpressure throttle).

clock:    T   T   T   T   T   T
events:   E E E E E E E E E E E
fires:    E   E   E   E   E   E
                  (dropped E's not shown above)

Throttle is the right tool for:

• API rate limits ("max 10 requests/sec to this third-party API")
• Log throttling ("max 100 identical log lines per minute")
• UI animation ("call the resize handler at most every 16ms = 60 FPS")
• Telemetry ("emit one metric snapshot per second")

8. The relationship between debounce, throttle, and timers¶

Debounce uses a resettable timer (time.AfterFunc is the easiest API, but time.Timer.Reset works too). Throttle uses a ticker (time.Ticker) or a non-resettable timer you re-arm yourself. Both rely on the same underlying runtime mechanism — the runtime.timer heap inside runtime/time.go — but they expose different shapes.

If you write time.AfterFunc to schedule "fire one thing in 300ms", and you Reset it every time an event arrives, you have built a debouncer. If you write time.NewTicker(300 * time.Millisecond) and you process at most one event per tick, you have built a throttler. The hard part is the bookkeeping around them, not the timer call itself.

Real-World Analogies¶

The elevator door (debounce)¶

An elevator door waits a few seconds before closing. Every time someone steps in or the "open" button is pressed, the countdown restarts. Only when nothing happens for, say, three seconds does the door finally close. That is a trailing-edge debouncer with a 3-second window.

The bouncer at a club (throttle)¶

The bouncer at a busy club lets one person in every ten seconds. People may form a line, but the rate at which they enter is fixed. If too many gather, some give up and leave (drop policy); some wait patiently (queue policy); some get angry and shout, putting pressure on the bouncer (backpressure policy). Whatever the queue does, the rate of admission is constant.

The cassette tape rewind button (leading debounce)¶

On an old Walkman, pressing rewind once would start rewinding; pressing it ten more times in two seconds did nothing extra. That is a leading-edge debounce: the first press wins and the rest are absorbed.

The fire-and-forget photo flash (throttle by interval)¶

A camera flash recharges for a couple of seconds after firing. You can press the shutter as fast as you like; the flash will only go off when the capacitor is full. That is a token bucket of size 1 with a slow refill rate.

The petrol station with one pump (token bucket)¶

Imagine a station with a bucket holding ten litres of "free flow". Customers pour into the bucket at a rate of one litre per second. Anyone arriving while the bucket has fuel can take exactly what they need; if the bucket is empty they wait. A burst of customers in the first minute can each get a litre, but the eleventh in quick succession has to wait for refill. That is a token bucket with burst 10 and rate 1/sec.

The sieve dripping water (leaky bucket)¶

A sieve holds water; water drips out at a constant rate. No matter how fast you pour, the output is fixed. There is no "burst capacity" — even if the sieve is empty when you start pouring, the first drops still drip at the steady output rate. That is a leaky bucket.

A telephone exchange (sliding window)¶

Old phone exchanges allowed only N simultaneous calls. The exchange counted calls in the last sixty seconds and refused any over a threshold. That is a sliding window rate limit.

Mental Models¶

Mental model 1: the "stretchy ribbon" debounce¶

Picture a rubber ribbon stretched between you and a button. Every event pulls the ribbon a little tighter, restarting a stopwatch. When the stopwatch reaches zero without being touched, the ribbon snaps back, the button is pressed, and one signal escapes. This captures the resettable nature of debounce: each event delays the firing, and only the absence of further events finally permits a fire.

Mental model 2: the "metronome" throttle¶

Picture a metronome clicking once per second. The throttle is a small gate that opens for one event whenever the metronome clicks and closes again right after. Events arriving while the gate is shut bounce off or queue up. This captures the time-driven nature of throttle: the metronome ticks regardless of whether events arrive, and the throttle's behaviour is entirely a function of "is the gate open right now?".

Mental model 3: the "savings account" token bucket¶

The token bucket is a savings account that earns interest at a fixed rate. You start with B dollars. The bank adds one dollar per second up to a max balance of B. Each event withdraws one dollar. If the balance is zero you cannot spend. This captures both the burst and the steady-state rate: you can spend B dollars in one go after a long pause, but over the long run you can only spend at the refill rate.

Mental model 4: the "buffered pipe" leaky bucket¶

The leaky bucket is a pipe with a small hole. You can pour water in arbitrarily fast; the pipe leaks at a fixed rate. If you pour faster than it leaks, the pipe overflows (events dropped). This captures the no-burst nature of the leaky bucket: even from empty, the output is paced.

Mental model 5: the "rolling 60-second tally" sliding window¶

The sliding window is a slip of paper on which you write the timestamp of every event in the last minute. Whenever a new event arrives you first scratch out timestamps older than 60 seconds, then count remaining entries. If the count is at the limit, reject. This is the most accurate rate limit but uses the most memory.

Mental model 6: the "state machine" view¶

Both debounce and throttle are tiny state machines with two states:

• Debounce: Idle ↔ Pending. Events move you into Pending and re-arm the timer; the timer expiring moves you back to Idle and fires the callback.
• Throttle: Open ↔ Closed. The clock opens the gate; firing closes it.

If you write a debounce or throttle and cannot draw the state machine in two boxes, you have over-engineered.

Pros and Cons¶

Debounce¶

Pros

• Collapses bursts to one event — minimal downstream work
• The last event in a burst carries the latest data (good for "save", "search", "auto-update")
• Simple to implement with time.AfterFunc
• No queue → constant memory

Cons

• Adds latency equal to the debounce window (300ms means a 300ms delay on every burst end)
• Discards all intermediate events — they are gone forever
• If the burst never ends, the debouncer never fires (rare but real for "keepalive" pings)
• Hard to reason about under cancellation: did the last event fire before context expired?

Throttle¶

Pros

• Deterministic output rate — exactly N events per second, no more
• Backpressure-friendly — can block producers cleanly
• Composes well with downstream rate limits (API quotas, write budgets)
• Token-bucket variant allows controlled bursting

Cons

• Drops or queues data unless you do extra work
• A naive ticker implementation leaks goroutines if not stopped
• Wall-clock jitter can let multiple events through in one window
• More moving parts than debounce (ticker, queue, drop policy)

Comparison table¶

Use Cases¶

Debounce¶

1. Search-as-you-type. Fire the search query 300ms after the user stops typing.
2. Auto-save. Save the document one second after the last keystroke.
3. Resize listeners. Recompute layout once after the window stops resizing.
4. Config reload. Reload config 500ms after the last filesystem event in a burst.
5. Form validation. Validate one second after the user stops typing.
6. Mouse hover tooltips. Show the tooltip 400ms after the cursor lands and stops.
7. Database write coalescing. Persist state 200ms after the last in-memory mutation.

Throttle¶

1. API rate limits. Stay under 10 requests/sec to a third-party API.
2. Log throttling. Max 1 line/sec of "DB unavailable" no matter how many failures.
3. Metrics emission. One snapshot per second to Prometheus, not one per event.
4. Scroll handlers. Run the scroll callback at most every 16ms.
5. WebSocket broadcasts. Send at most 30 frames/sec per peer.
6. Background polling. Hit the upstream once per minute even if event sources fire faster.
7. Login attempt rate-limits. Max 5 attempts/minute per IP.
8. CDN purge requests. Coalesce and pace cache invalidations.

Both together¶

1. Search box. Debounce keystrokes to one request and throttle to max 2 requests/sec to protect the backend.
2. Editor save. Debounce typing to one save and throttle saves to max 10/min to limit S3 writes.
3. IoT sensor ingest. Debounce per-device updates to coalesce noise, throttle total ingest rate to protect Kafka.

Code Examples¶

Example 1: the simplest possible debouncer¶

The smallest correct trailing-edge debouncer in Go is built on time.AfterFunc. A *time.Timer is created once; every call to Trigger resets it. Only the last call's Reset will actually let the timer expire and run the registered function.

package debounce

import (
    "sync"
    "time"
)

// Debouncer is a trailing-edge debouncer. Construct one with New, call Trigger
// every time an event happens, and the supplied fn will run once, `wait` after
// the last Trigger.
type Debouncer struct {
    mu    sync.Mutex
    wait  time.Duration
    fn    func()
    timer *time.Timer
}

// New returns a Debouncer that will call fn once `wait` has elapsed without
// any further calls to Trigger.
func New(wait time.Duration, fn func()) *Debouncer {
    return &Debouncer{wait: wait, fn: fn}
}

// Trigger restarts the countdown. Safe to call from any goroutine.
func (d *Debouncer) Trigger() {
    d.mu.Lock()
    defer d.mu.Unlock()
    if d.timer != nil {
        d.timer.Stop()
    }
    d.timer = time.AfterFunc(d.wait, d.fn)
}

Usage:

func ExampleDebouncer() {
    deb := New(200*time.Millisecond, func() {
        println("fired")
    })
    deb.Trigger()
    deb.Trigger()
    deb.Trigger()
    time.Sleep(300 * time.Millisecond)
    // prints "fired" exactly once
}

The whole pattern: Stop the old timer, create a new one. The Go runtime takes care of the heap, the goroutine that fires fn, and the cleanup.

Why we hold a mutex¶

Two goroutines calling Trigger simultaneously could race on d.timer. The mutex turns the two operations (Stop then assign) into one atomic update.

Why we don't worry about the old timer's goroutine¶

AfterFunc only schedules a goroutine when the timer fires. Calling Stop before fire prevents the goroutine from running. We never have an orphan.

Example 2: debounce wrapping a payload¶

The earlier debouncer fires a fixed function with no input. In real systems the event carries data and the action should use the latest data. A typed wrapper:

package debounce

import (
    "sync"
    "time"
)

type PayloadDebouncer[T any] struct {
    mu      sync.Mutex
    wait    time.Duration
    fn      func(T)
    latest  T
    hasItem bool
    timer   *time.Timer
}

func NewPayload[T any](wait time.Duration, fn func(T)) *PayloadDebouncer[T] {
    return &PayloadDebouncer[T]{wait: wait, fn: fn}
}

func (d *PayloadDebouncer[T]) Trigger(v T) {
    d.mu.Lock()
    d.latest = v
    d.hasItem = true
    if d.timer != nil {
        d.timer.Stop()
    }
    d.timer = time.AfterFunc(d.wait, d.fire)
    d.mu.Unlock()
}

func (d *PayloadDebouncer[T]) fire() {
    d.mu.Lock()
    v := d.latest
    had := d.hasItem
    d.hasItem = false
    d.mu.Unlock()
    if had {
        d.fn(v)
    }
}

Usage:

func ExamplePayloadDebouncer() {
    deb := NewPayload[string](300*time.Millisecond, func(q string) {
        println("search:", q)
    })
    deb.Trigger("g")
    deb.Trigger("go")
    deb.Trigger("gol")
    deb.Trigger("gola")
    deb.Trigger("golan")
    deb.Trigger("golang")
    time.Sleep(400 * time.Millisecond)
    // prints exactly once: "search: golang"
}

Why the second mutex acquisition in fire¶

fire runs in the timer's goroutine. By the time it runs, more Trigger calls might have updated d.latest. The lock makes the read of latest and reset of hasItem atomic with whatever else is happening on Trigger.

Why hasItem¶

It guards against the rare race in which Stop returned false (because the timer was already firing), the next call replaced d.timer, and we still got a callback from the old timer firing. In that case hasItem may still be true but we have already scheduled a fresh fire, so we will deliver one extra. That is acceptable for now; we will tighten this up in middle.md.

Example 3: simplest throttler with time.Ticker¶

Now the throttle. We want to admit one event per interval. The simplest design is a ticker plus a single-slot channel:

package throttle

import (
    "context"
    "time"
)

// Throttle reads from `in`, emits at most one event per `interval` on the
// returned channel, and drops anything else. It exits when ctx is cancelled
// or `in` is closed.
func Throttle[T any](ctx context.Context, in <-chan T, interval time.Duration) <-chan T {
    out := make(chan T, 1)
    go func() {
        defer close(out)
        tick := time.NewTicker(interval)
        defer tick.Stop()
        var pending T
        var hasPending bool
        for {
            select {
            case <-ctx.Done():
                return
            case v, ok := <-in:
                if !ok {
                    return
                }
                pending = v
                hasPending = true
            case <-tick.C:
                if hasPending {
                    select {
                    case out <- pending:
                        hasPending = false
                    default:
                        // downstream slow; drop
                    }
                }
            }
        }
    }()
    return out
}

This throttle has two important properties:

1. The output rate is at most 1 per interval. Bursts on in are coalesced to the latest unread event.
2. If the downstream consumer is slow, events are dropped silently. That is a defensible default for log throttling; it would be wrong for a throttler in front of a payment API where every event must be delivered.

Example 4: throttle with a leading-edge fire¶

The previous throttle waits for the first tick before emitting anything, which means up to one full interval of latency before the first event escapes. A leading-edge throttle fires the very first event immediately:

package throttle

import (
    "context"
    "time"
)

func ThrottleLeading[T any](ctx context.Context, in <-chan T, interval time.Duration) <-chan T {
    out := make(chan T, 1)
    go func() {
        defer close(out)
        var last time.Time
        for {
            select {
            case <-ctx.Done():
                return
            case v, ok := <-in:
                if !ok {
                    return
                }
                now := time.Now()
                if last.IsZero() || now.Sub(last) >= interval {
                    out <- v
                    last = now
                }
                // else: drop
            }
        }
    }()
    return out
}

This is "drop everything inside the cooldown" semantics. It is simple, correct, and pulls no extra goroutines. The downside is jitter: if events arrive at exactly the same wall-clock instant from multiple sources, they may all pass or all drop together. For UI scroll handlers this is fine; for hard rate limits you want a ticker-backed version.

Example 5: a debounce running across a channel¶

So far the Debouncer exposed a Trigger method. In Go we often prefer channels for everything. Here is the same logic packaged as a channel-to-channel converter:

package debounce

import (
    "context"
    "time"
)

func DebounceCh[T any](ctx context.Context, in <-chan T, wait time.Duration) <-chan T {
    out := make(chan T, 1)
    go func() {
        defer close(out)
        var pending T
        var hasPending bool
        var timer *time.Timer
        var timerC <-chan time.Time
        for {
            select {
            case <-ctx.Done():
                if timer != nil {
                    timer.Stop()
                }
                return
            case v, ok := <-in:
                if !ok {
                    if hasPending {
                        select {
                        case out <- pending:
                        case <-ctx.Done():
                        }
                    }
                    return
                }
                pending = v
                hasPending = true
                if timer == nil {
                    timer = time.NewTimer(wait)
                } else {
                    if !timer.Stop() {
                        select {
                        case <-timer.C:
                        default:
                        }
                    }
                    timer.Reset(wait)
                }
                timerC = timer.C
            case <-timerC:
                if hasPending {
                    select {
                    case out <- pending:
                        hasPending = false
                    case <-ctx.Done():
                        return
                    }
                }
                timerC = nil
            }
        }
    }()
    return out
}

Read this slowly. The pattern is:

• Maintain a *time.Timer only when an event is pending
• timerC is the channel to read from; it is nil when no event is pending — recall that a nil channel in select is never ready, which is exactly how we "disable" that branch
• On event: update pending, create or Reset the timer
• On timer fire: deliver pending, disable the timer branch
• On context cancel: stop the timer, return

Why drain timer.C inside the Stop-false branch¶

When timer.Stop returns false it means the timer already fired (or was already stopped). If we do not drain timer.C, the next Reset could give us a stale fire from the old firing. The non-blocking select drains it if present.

This idiom — Stop then drain — is the single most important pattern in Go timer code. It is covered in 03-timer-leaks and is repeated in every production debounce and throttle.

Example 6: a leading throttle backed by time.Now¶

The simplest throttle does not need any goroutines or channels at all. It is a struct holding the last-fire time and a mutex:

package throttle

import (
    "sync"
    "time"
)

type Limiter struct {
    mu       sync.Mutex
    interval time.Duration
    last     time.Time
}

func New(interval time.Duration) *Limiter {
    return &Limiter{interval: interval}
}

// Allow returns true if an event is allowed right now.
func (l *Limiter) Allow() bool {
    now := time.Now()
    l.mu.Lock()
    defer l.mu.Unlock()
    if l.last.IsZero() || now.Sub(l.last) >= l.interval {
        l.last = now
        return true
    }
    return false
}

Usage:

func ExampleLimiter() {
    l := New(500 * time.Millisecond)
    for i := 0; i < 10; i++ {
        if l.Allow() {
            println("fire", i)
        }
        time.Sleep(100 * time.Millisecond)
    }
    // prints "fire 0", "fire 5"
}

This pattern is so common that the standard library effectively provides it via golang.org/x/time/rate. We will introduce that in middle.md. For now, the hand-rolled version is a fine starting point and works without external dependencies.

Example 7: throttle that blocks instead of dropping¶

Sometimes you want callers to wait until the next token rather than be silently rejected. The cheapest version is a time.Ticker wrapped in a method:

package throttle

import (
    "context"
    "time"
)

type BlockingLimiter struct {
    tick *time.Ticker
}

func NewBlocking(interval time.Duration) *BlockingLimiter {
    return &BlockingLimiter{tick: time.NewTicker(interval)}
}

func (b *BlockingLimiter) Wait(ctx context.Context) error {
    select {
    case <-b.tick.C:
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

func (b *BlockingLimiter) Close() {
    b.tick.Stop()
}

Usage:

func sendBatch(ctx context.Context, items []Item) error {
    l := NewBlocking(100 * time.Millisecond)
    defer l.Close()
    for _, it := range items {
        if err := l.Wait(ctx); err != nil {
            return err
        }
        send(it)
    }
    return nil
}

This is the simplest correct implementation of "block until I'm allowed to send", and it composes naturally with context for cancellation. Its weakness is that the ticker keeps running even when nobody is waiting — that wastes a goroutine wakeup per interval. For low-frequency limiters this is negligible; for very high-frequency ones we will reach for rate.Limiter in middle.md.

Example 8: combining debounce and throttle¶

Real systems often want both. A search box should debounce typing into one query and then throttle queries to protect the backend. Here is the wiring:

package pipeline

import (
    "context"
    "time"

    "example.com/debounce"
    "example.com/throttle"
)

func SearchPipeline(ctx context.Context, keystrokes <-chan string) <-chan string {
    debounced := debounce.DebounceCh(ctx, keystrokes, 300*time.Millisecond)
    throttled := throttle.Throttle(ctx, debounced, 500*time.Millisecond)
    return throttled
}

Three lines. The keystroke channel becomes a debounced channel, which becomes a throttled channel. Notice that each stage runs in its own goroutine — that is the entire point of channel-based composition. We will return to this layered design in middle.md and professional.md.

Example 9: a debouncer that knows about cancellation¶

The debouncers above accept context.Context and exit on ctx.Done(). A subtle question: should a pending event still fire after the context is cancelled?

The general answer is no. Once the context is cancelled the consumer has stopped listening. Firing the timer's callback may write into a closed channel and panic, or may do unwanted work after the request has been abandoned.

The patterns in this file all stop the timer on context cancellation and do not fire any pending event. In middle.md we will explore the alternate policy ("fire on cancel") for completeness, but the default is "cancel means discard".

Example 10: a small end-to-end runnable demo¶

To tie this together, here is a complete program you can run with go run:

package main

import (
    "context"
    "fmt"
    "time"
)

type Debouncer struct {
    wait  time.Duration
    in    chan string
    out   chan string
    done  chan struct{}
}

func NewDebouncer(wait time.Duration) *Debouncer {
    d := &Debouncer{
        wait: wait,
        in:   make(chan string, 16),
        out:  make(chan string, 1),
        done: make(chan struct{}),
    }
    go d.loop()
    return d
}

func (d *Debouncer) loop() {
    defer close(d.out)
    var pending string
    var hasPending bool
    var timer *time.Timer
    var timerC <-chan time.Time
    for {
        select {
        case <-d.done:
            if timer != nil {
                timer.Stop()
            }
            return
        case v, ok := <-d.in:
            if !ok {
                return
            }
            pending = v
            hasPending = true
            if timer == nil {
                timer = time.NewTimer(d.wait)
            } else {
                if !timer.Stop() {
                    select {
                    case <-timer.C:
                    default:
                    }
                }
                timer.Reset(d.wait)
            }
            timerC = timer.C
        case <-timerC:
            if hasPending {
                d.out <- pending
                hasPending = false
            }
            timerC = nil
        }
    }
}

func (d *Debouncer) Trigger(v string) {
    d.in <- v
}

func (d *Debouncer) Out() <-chan string { return d.out }

func (d *Debouncer) Close() {
    close(d.done)
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    deb := NewDebouncer(300 * time.Millisecond)
    defer deb.Close()

    go func() {
        for v := range deb.Out() {
            fmt.Println("delivered:", v)
        }
    }()

    for _, c := range "golang" {
        deb.Trigger(string(c))
        time.Sleep(50 * time.Millisecond)
    }

    <-ctx.Done()
}

Output:

delivered: g

Wait — that is the first letter, not the last. Why? Because time.Sleep(50ms) between letters is less than the 300ms debounce, so every letter resets the timer; only after the loop ends and we sleep do we actually get a fire — and the latest letter is g. Let me trace it more carefully:

Actually the loop sends g, o, l, a, n, g and the last is g. So output is delivered: g. If we change the loop to type golang!, the output would be delivered: !. The point is: trailing debounce always delivers the last event, no matter how many came before.

Run this program and play with the sleep duration. With 50ms, all letters arrive within one debounce window. With 400ms, each letter triggers its own fire, and you will see every character delivered.

Coding Patterns¶

Pattern 1: AfterFunc + Stop + assign¶

if d.timer != nil {
    d.timer.Stop()
}
d.timer = time.AfterFunc(d.wait, d.fn)

The simplest correct debounce primitive. We discard the return of Stop because AfterFunc schedules its own goroutine and we just want the previous schedule cancelled. If Stop returned false (timer already fired), we accept that the old fn might have just run — that is no worse than the old behaviour and our new schedule is correct.

Pattern 2: nil-channel disable¶

var timerC <-chan time.Time
for {
    select {
    case <-timerC: // never ready when timerC is nil
        ...
    }
}

A nil channel in a select is never ready. This is the Go-idiomatic way to "disable" a branch of a select. Use it to express "no timer is currently armed" without ad-hoc booleans.

Pattern 3: Stop-then-drain Reset dance¶

if !timer.Stop() {
    select {
    case <-timer.C:
    default:
    }
}
timer.Reset(d)

When you reset a time.Timer (not AfterFunc), you must handle the case where it already fired. Stop returns false if it cannot prevent the fire. The non-blocking receive drains the channel if a value is sitting there. This avoids a stale value triggering the next fire prematurely.

In Go 1.23+ the runtime made this safer — bare Reset is now safe in most cases — but the explicit pattern still works on every version and is the canonical idiom.

Pattern 4: ticker + buffered out-channel + drop¶

out := make(chan T, 1)
for {
    select {
    case v := <-in:
        pending = v
        hasPending = true
    case <-tick.C:
        if hasPending {
            select {
            case out <- pending:
                hasPending = false
            default:
            }
        }
    }
}

This is the lossy throttle. The inner non-blocking send means "if the downstream is full, drop". It is appropriate for logs, metrics, UI updates — anything where the latest value is fine and dropping is acceptable.

Pattern 5: blocking throttle¶

out := make(chan T)
for v := range in {
    <-tick.C
    out <- v
}

The lossless throttle. Senders block on tick.C. The downstream gets one event per interval and every event is preserved (subject to the input channel's capacity). The cost is that producers must tolerate blocking.

Pattern 6: leading-edge "if-elapsed"¶

now := time.Now()
if now.Sub(last) >= interval {
    last = now
    // fire
}

No goroutines, no channels, no timers. Just timestamps. This is the implementation strategy of every "leading throttle" in the wild. It is so cheap that it shows up in tight loops where allocating a goroutine would be silly.

Pattern 7: context-aware exit¶

select {
case v := <-in:
    ...
case <-ctx.Done():
    if timer != nil { timer.Stop() }
    return
}

Always provide a way out. A debounce or throttle goroutine that cannot be cancelled is a goroutine leak waiting to happen. The ctx.Done() branch is non-negotiable in any production code.

Clean Code¶

Name your debouncers and throttlers for what they coalesce or pace¶

A name like saveDebouncer or searchDebouncer makes the call site read like English: searchDebouncer.Trigger(query). A name like d, db, dbnc makes the call site obscure.

Keep the function signature symmetric for debounce and throttle¶

Both should accept a context.Context first, an input channel second, and a duration third. The output channel should be the return value. The reader can then guess the API without reading the doc:

func Debounce[T any](ctx context.Context, in <-chan T, wait time.Duration) <-chan T
func Throttle[T any](ctx context.Context, in <-chan T, interval time.Duration) <-chan T

Encapsulate the goroutine¶

Never expose a public Loop() method that callers are expected to run in a goroutine. Spawn the goroutine inside the constructor (or the channel-pipeline function) and return the public surface. Callers should not have to remember "and also run go d.Loop()".

One responsibility per type¶

A Debouncer debounces. It does not also throttle, batch, or persist. If you find your struct sprouting flags like withBatching bool, withThrottling bool, split it. Composition through channels is your friend.

Make the firing function explicit¶

A debouncer that calls a func() is fine; a debouncer that emits to a channel is fine. A debouncer that does both, depending on a flag, is not fine. Pick one in the public API and let the other be implemented in terms of it.

Always document the window¶

NewDebouncer(300 * time.Millisecond, save) is a call site that benefits from a comment: // 300ms after the last edit, persist to disk. In production code that comment is documentation; in junior code it is a teaching tool.

Stop ticks in a Close method¶

Every long-lived throttler should expose Close. Inside, call Stop on the ticker. If you forget, the runtime will keep the ticker timer alive forever, which is a tiny memory leak in tests and a real one in long-running processes.

Product Use and Feature¶

Imagine you are building a markdown note-taking app. The product manager says:

• "When the user stops typing for half a second, save."
• "Don't hit the server more than twice a second even if the user types like a maniac."
• "When connectivity is bad, queue saves and don't lose data."

That is one debounce, one throttle, and one buffered queue. The architecture writes itself:

keystroke chan → DebounceCh(500ms) → ThrottleBlocking(500ms) → save()

The DebounceCh collapses bursts; the ThrottleBlocking paces; the channel between them buffers if needed. A two-line wiring beats a hundred-line custom save-controller every time.

Real-life feature: file-watch reload¶

A common feature in tooling: when a config file changes, reload it. File systems generate multiple "write" events for one save (open, write, close = 3 events on Linux). Without a debouncer your tool reloads the config three times in a row, which is at best a waste and at worst a half-written file being read.

watcher.Events → DebounceCh(100ms) → reloadConfig()

Done.

Real-life feature: error suppression¶

A logger that prints connection refused once per second instead of once per call:

errCh → Throttle(1 * time.Second) → log.Println

The first error fires immediately (with a leading throttle), and subsequent errors in the next second are dropped. The on-call engineer sees one line per second, not ten thousand.

Error Handling¶

The patterns in this file mostly process events of an opaque type. Errors live alongside events as part of the payload — typically chan Result[T] or chan struct{ V T; Err error }. The debouncer or throttler does not know what an "error" is; it just relays the payload.

That said, there are a few error-shaped things specific to debounce and throttle:

Context cancellation¶

If the context is cancelled while an event is pending, do not deliver it. Discard it. The consumer is no longer listening.

case <-ctx.Done():
    if timer != nil { timer.Stop() }
    return // do not flush

Producer close¶

If the input channel is closed while an event is pending, the right behaviour usually is to deliver the pending event (it would have been delivered eventually). After the flush, exit:

case v, ok := <-in:
    if !ok {
        if hasPending {
            select {
            case out <- pending:
            case <-ctx.Done():
            }
        }
        return
    }
    ...

Downstream full¶

If the output channel is full and you have a lossy throttle, drop. If you have a lossless throttle, block on the send and accept backpressure. The choice is product-driven; document it loudly.

Panic safety in AfterFunc¶

time.AfterFunc(d, f) runs f in a goroutine. If f panics it kills the whole program. Always recover inside the supplied function for production code:

time.AfterFunc(d, func() {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("debounce fn panic: %v", r)
        }
    }()
    fn()
})

We will revisit panic safety in professional.md.

Security Considerations¶

Debounce and throttle are themselves security primitives — they are how you implement rate-limiting on login attempts, password resets, API keys, and other abuse surfaces. A few things to be aware of even at the junior level:

Don't use debounce as a rate limit¶

A debouncer absorbs bursts but allows arbitrary frequency over the long run. If you debounce password reset emails by 5 seconds, an attacker can still send one every 5 seconds forever — that is one per second of average rate which is not what you want. Use throttle for security limits.

Per-actor isolation¶

A single shared throttle limits the whole system. For abuse prevention you want a throttle per IP, per user, or per API key. That means a map[Actor]*Limiter with eviction. We will design that in senior.md.

Beware time-based side channels¶

If your "Allow" function takes substantially longer when the throttle rejects than when it permits, an attacker can deduce rate-limit state from response time. Make both paths constant-time-ish (the simple Allow above already is, because the cost difference between "compare and return true" and "return false" is negligible).

Resource exhaustion¶

A throttle that queues unbounded events will eat all your memory. Always use a bounded queue (or no queue and the drop policy) when the actor is untrusted.

Performance Tips¶

time.AfterFunc allocates¶

Every call to AfterFunc allocates a *time.Timer and a goroutine. For a debouncer that fires hundreds of times per second this adds up. A single time.Timer reused via Reset allocates exactly once. Prefer the reuse pattern for hot debouncers.

time.Now is fast but not free¶

On Linux/amd64 a time.Now() call is ~20ns and a time.Since is a subtraction plus a Now. On hot paths (millions of calls per second) you may want to amortise — call time.Now once per batch. We will get into this in senior.md and optimize.md.

Avoid creating a new ticker per request¶

A time.NewTicker returned by your throttler should be created once and shared across calls. Creating one per request makes the runtime's timer heap dance for every event.

Buffered output for throttles¶

make(chan T, 1) instead of make(chan T) removes one rendezvous from the hot path. The throttle's tick branch can deliver and continue without waiting for the consumer to be ready.

Don't channel a single-bit signal¶

If the consumer just needs to know "an event is pending", chan struct{} with capacity 1 is the right type, not chan bool and not chan int. The compiler knows struct{} has zero size.

Best Practices¶

1. Always document the window. "Debounce 300ms" or "Throttle 1/sec" should appear in the call site comment or constructor argument name.
2. Always provide cancellation. Either a context.Context parameter or a Close() method. Long-lived goroutines without cancellation are leaks.
3. Default to trailing-edge debounce. It is the variant 95% of use cases want. If you need leading, name the constructor NewLeadingDebouncer so it is obvious at the call site.
4. Default to lossy throttle for logs and metrics, lossless for API quotas. Picking the wrong default produces either dropped business events or memory bloat.
5. Test with time.Tick(time.Microsecond)-driven input to force the timer paths. A debouncer that "works" with 1-second test inputs may have unhandled edge cases at 1-microsecond inputs.
6. Never share a Debouncer between contexts. If Trigger is called from request A's context and the timer fires after request B's context cancels, things get messy. One context per debouncer is the safe rule.
7. Prefer AfterFunc for fire-once-then-rearm semantics. It is shorter and the runtime handles the goroutine. Use time.Timer + Reset only when you need to read from timer.C inside a select.
8. Stop tickers in defer. defer tick.Stop() is one line and prevents a runtime timer leak.
9. Drain timer.C after Stop only when Stop returns false. Draining when Stop returned true is a bug — there is nothing to drain and the select will block.
10. Treat a nil channel as "disabled branch". It is the cleanest way to express "no timer armed".

Edge Cases and Pitfalls¶

Pitfall 1: the trigger that never fires¶

deb := New(1 * time.Second, save)
for range events {
    deb.Trigger()
    time.Sleep(500 * time.Millisecond)
}

If events never stop for a full second, the debouncer never fires. This is by design — there is no quiet period. The fix is either to use a throttle (which is time-driven and fires regardless of quiet) or to add a "maximum wait" to your debounce — combined-mode debounce, covered in middle.md.

Pitfall 2: the timer that fires after Close¶

deb := New(300 * time.Millisecond, save)
deb.Trigger()
deb.Close()
// 300ms later, save() is called anyway because we forgot to Stop the timer

Close must stop the timer. The simple debouncer above did not have a Close. In middle.md we will add one.

Pitfall 3: missed first event¶

out := Throttle(ctx, in, 1 * time.Second)
in <- "first"
v := <-out
// blocked for up to 1 second before "first" emerges

The ticker-based throttle delays the first event by up to a full tick. If you want the first event immediately, use the leading-throttle variant.

Pitfall 4: ticker drift on slow consumers¶

tick := time.NewTicker(100 * time.Millisecond)
for range tick.C {
    slowWork() // takes 200ms
}

If slowWork is slower than the tick, tick.C accumulates pending values. The loop ends up "playing catch-up" and runs back-to-back. For throttling, this is what you want — but for "pace work to 10/sec" it is wrong because you actually run 20/sec for a while. The fix is to read from tick.C once per loop and discard if late, or use rate.Limiter.

Pitfall 5: capturing the loop variable¶

for _, e := range events {
    deb := New(100*time.Millisecond, func() {
        fmt.Println(e) // always prints the last e in Go < 1.22
    })
    deb.Trigger()
}

Pre-Go-1.22, the closure captures e by reference. In Go 1.22+ this is fixed at the language level. But debounce callbacks are common offenders. Always capture explicitly:

e := e
deb := New(100*time.Millisecond, func() {
    fmt.Println(e)
})

Pitfall 6: race on latest¶

In our PayloadDebouncer we held a mutex. Without the mutex, two goroutines calling Trigger and the timer goroutine calling fire race on latest. Even reads of a string are not atomic — they consist of pointer + length. Always lock.

Pitfall 7: time.Tick (note: no New) cannot be stopped¶

for t := range time.Tick(time.Second) {
    ...
}

time.Tick returns a channel from a ticker that you can never stop. It is a leak. Use time.NewTicker and defer t.Stop().

Pitfall 8: throttle output channel closed too eagerly¶

go func() {
    defer close(out)
    for v := range in {
        ...
    }
}()

If in is closed but the throttle has a pending event, the pending event is lost unless you flush. The DebounceCh example above flushes on close; many production throttles do not, depending on policy.

Pitfall 9: clock skew¶

time.Now is wall-clock time. If the system clock jumps (NTP correction, VM resume) your throttle may briefly fire a flurry of events. Use time.Since on a time.Now recorded at startup, or even better, the monotonic clock — which Go's time.Now already records since Go 1.9. Comparing two time.Now results is monotonic by default; comparing one to a hard-coded time.Time literal is not.

Pitfall 10: AfterFunc panics¶

time.AfterFunc(d, func() {
    panic("oops")
})

This kills the process. Recover inside.

Common Mistakes¶

1. Confusing debounce and throttle. They sound similar; they are not. Re-read the "fundamental distinction" section if you ever waver.
2. Reaching for debounce when throttle is needed (or vice versa). Search box → debounce; API call → throttle.
3. Not stopping tickers. time.NewTicker without Stop is a long-running leak.
4. Forgetting to drain timer.C after Stop-false. Causes stale fires.
5. Using time.Tick (no New). Cannot be stopped; in any but the shortest test programs this is a leak.
6. Sharing a debouncer across actors. One debouncer per actor (per user, per session, per file) is the rule.
7. Forgetting context.Context. Every long-lived goroutine should accept a context. Otherwise you cannot shut down gracefully.
8. Reading time.Now inside a tight loop with thousands of events per second. Amortise.
9. Allocating a *Limiter per request. Allocate once at startup, share via dependency injection.
10. Mixing leading and trailing semantics without naming them. The bug report will say "the button fires twice"; the cause is "I added trailing to a leading-only throttle".

Common Misconceptions¶

"Throttle and debounce are the same thing with different parameters."

No. They are different patterns. A debouncer with a 0-second window does not become a throttle; it becomes "call immediately on every event" — i.e. no rate limiting at all. A throttle with an infinite interval does not become a debouncer; it becomes "fire once and never again".

"Debounce is for input, throttle is for output."

No. Both can be applied at input or output. A search-box keystroke is input, debounced. An outbound HTTP call is output, throttled. A websocket from a peer is input, throttled (to protect us). A toast notification is output, debounced (so we don't spam the user).

"If I use rate.Limiter I don't need to understand any of this."

rate.Limiter is excellent and we use it heavily in middle.md and beyond. But you still need to know when to reach for debounce vs throttle, what bucket size to set, what to do on rejection. The library does not decide that for you.

"Throttle adds latency."

Lossy throttle adds at most one interval of latency to the first event of a burst (with a ticker-backed implementation; zero with a leading implementation). Blocking throttle can add unbounded latency for late events in a burst. Debounce adds exactly the window's worth of latency to the last event.

"I can just use time.Sleep."

time.Sleep paces a single producer. It does not throttle multiple concurrent producers, does not interact with channels, and does not respect cancellation cleanly.

Tricky Points¶

Tricky point 1: Reset semantics changed in Go 1.23¶

Before Go 1.23, calling t.Reset on a *time.Timer that had already fired could leave a stale value in t.C. The canonical workaround was the Stop-then-drain dance. From Go 1.23, the runtime made Reset safer by re-using the same channel and ensuring a single fire is delivered. The Stop-then-drain dance is still correct on all versions, just no longer required on 1.23+. Junior code should use the older idiom for portability.

Tricky point 2: AfterFunc vs NewTimer¶

time.AfterFunc(d, f) runs f in a fresh goroutine when the timer fires. You cannot read from timer.C because there is no timer.C channel exposed to you. You also do not need a select.

time.NewTimer(d) returns a timer with a timer.C channel of buffer 1. You can include <-timer.C in a select and decide whether to fire based on which branch wins.

Use AfterFunc for fire-and-forget (the simple debouncer). Use NewTimer when the timer participates in a select (the channel-based debouncer).

Tricky point 3: Stop returns bool¶

t.Stop() returns true if the call stopped the timer before it fired; false if it had already fired (or already been stopped). Production code uses that return value to decide whether to drain.

Tricky point 4: goroutines from AfterFunc that already started¶

If Stop returns false, the timer's goroutine has already started running your fn. Stopping does not cancel an already-running fn. If you needed to abort the work — you cannot. The fix is to put a cancellation check inside fn itself.

Tricky point 5: channels in select with closed sender¶

A closed channel becomes immediately ready. If you select on a closed channel, that branch will be chosen every time. Without an ok check and an explicit nil-out of that branch, you spin-loop. Always check ok:

case v, ok := <-in:
    if !ok {
        in = nil // disable this branch
        continue
    }

Tricky point 6: ticker drift¶

time.NewTicker(100ms) tries to fire every 100ms, but if the consumer is slow and the channel buffer fills (buffer is 1 for a ticker), the runtime drops ticks. The ticker does not "catch up" beyond the next scheduled fire. This is good for throttling (we never want a burst out the other side) but surprising.

Tricky point 7: timers vs runtime.timer¶

Internally Go maintains a heap of timers in runtime/time.go. Creating millions of time.AfterFunc calls is fine for short-lived programs but can pressure the timer heap. For very high-frequency debouncing consider sharing a single timer that you Reset repeatedly.

Tricky point 8: GC and timers¶

A *time.Timer that has been Stoped and is no longer referenced is collected. A *time.Timer you keep a reference to but never Stop will not be GC'd until it fires. So long-lived debouncers that never fire (rare) can hold timers indefinitely.

Tricky point 9: time.Now and timestamps¶

time.Now() returns a time.Time with both wall-clock and monotonic components. Sub between two such values uses monotonic, so it is correct across NTP adjustments. But if you serialize a time.Time to JSON and back, the monotonic component is lost. Be careful in distributed systems.

Tricky point 10: zero-value time.Time¶

A time.Time whose underlying state is the zero value satisfies t.IsZero() == true. Comparisons like now.Sub(zero) are valid but yield a very large number (~292 years). Use IsZero checks before doing the math.

Test¶

package debounce

import (
    "context"
    "sync/atomic"
    "testing"
    "time"
)

func TestDebouncerFiresOnce(t *testing.T) {
    var hits int32
    d := New(50*time.Millisecond, func() {
        atomic.AddInt32(&hits, 1)
    })
    for i := 0; i < 10; i++ {
        d.Trigger()
        time.Sleep(10 * time.Millisecond)
    }
    time.Sleep(100 * time.Millisecond)
    if got := atomic.LoadInt32(&hits); got != 1 {
        t.Fatalf("expected 1 fire, got %d", got)
    }
}

func TestDebouncerFiresPerBurst(t *testing.T) {
    var hits int32
    d := New(50*time.Millisecond, func() {
        atomic.AddInt32(&hits, 1)
    })
    d.Trigger()
    time.Sleep(100 * time.Millisecond)
    d.Trigger()
    time.Sleep(100 * time.Millisecond)
    if got := atomic.LoadInt32(&hits); got != 2 {
        t.Fatalf("expected 2 fires, got %d", got)
    }
}

func TestDebounceChChannelClose(t *testing.T) {
    in := make(chan int, 8)
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()
    out := DebounceCh(ctx, in, 30*time.Millisecond)
    for i := 0; i < 5; i++ {
        in <- i
    }
    close(in)
    select {
    case v, ok := <-out:
        if !ok {
            t.Fatal("expected one value before close")
        }
        if v != 4 {
            t.Fatalf("expected 4, got %d", v)
        }
    case <-time.After(200 * time.Millisecond):
        t.Fatal("timeout")
    }
}

package throttle

import (
    "context"
    "testing"
    "time"
)

func TestThrottleRate(t *testing.T) {
    in := make(chan int, 100)
    ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
    defer cancel()
    out := Throttle(ctx, in, 100*time.Millisecond)
    go func() {
        for i := 0; i < 100; i++ {
            in <- i
        }
        close(in)
    }()
    var count int
    for range out {
        count++
    }
    // In 500ms with 100ms interval we should get ~5
    if count > 7 || count < 3 {
        t.Fatalf("expected ~5 events, got %d", count)
    }
}

func TestLimiterLeading(t *testing.T) {
    l := New(50 * time.Millisecond)
    if !l.Allow() {
        t.Fatal("first Allow should succeed")
    }
    if l.Allow() {
        t.Fatal("second immediate Allow should fail")
    }
    time.Sleep(60 * time.Millisecond)
    if !l.Allow() {
        t.Fatal("Allow after interval should succeed")
    }
}

Run these with go test -race -count=10 to shake out any rare races. The -count=10 is important; concurrency bugs love to hide in single runs.

Tricky Questions¶

Q1: A debouncer is configured with a 100ms window. Events arrive every 50ms forever. How many fires per minute?

A: Zero. The window never expires because events keep arriving. This is by design and is a known property of pure trailing debounce.

Q2: A throttle with a 1-second interval receives 10 events at time 0 and nothing after. How many fire and when?

A: One fires at time 0 (leading) or time 1s (trailing). Nine are dropped (lossy) or queue up to be delivered at 1s, 2s, … 9s (blocking).

Q3: If you call d.Trigger() once and then call d.Stop() before the window expires, does the fn ever run?

A: Not if Stop correctly stops the timer. Our basic example does not have a Stop method; you would add one that calls d.timer.Stop() under the mutex.

Q4: Why does a trailing debouncer "fire on close" of its input channel in the DebounceCh example?

A: Because closing the input is a strong signal that no more events are coming, so the latest pending event represents the final state and should not be lost. It is a policy choice; some debouncers discard pending events on close.

Q5: A throttler is implemented as a goroutine reading from in and sending to out. The caller forgets to read from out. What happens?

A: If out is unbuffered, the throttler blocks forever on send. If out is buffered, the throttler fills the buffer and then blocks. Either way you have a leaked goroutine. The drop policy (select { case out <- v: default: }) prevents this.

Q6: Why is time.Tick(d) considered harmful?

A: It returns the underlying ticker's channel but provides no way to access the ticker itself, so you cannot call Stop. The ticker leaks for the life of the program.

Q7: A debouncer is created inside an HTTP handler. The handler returns. Does the debouncer survive?

A: It survives as long as something references it. If you stored it in a map[user]*Debouncer it persists. If it was a local variable, it is GC'd. If you forgot to stop its timer it persists until the timer fires.

Q8: What's the difference between Throttle returning a <-chan T and Throttle taking a callback func(T)?

A: The channel version composes with other channel stages — pipelines. The callback version is more direct for one-shot use but ties the throttler to a specific kind of consumer. Library authors prefer channels.

Q9: A junior writes time.AfterFunc(d, fn) inside Trigger and never calls Stop on the old timer. What is the bug?

A: Each Trigger schedules a new fire without cancelling the old one. After N triggers within d, you get N fires. The fix is if old != nil { old.Stop() }; new = AfterFunc(...).

Q10: In the channel-based DebounceCh, why is timerC set to nil after a fire instead of just relying on the timer being expired?

A: A nil channel in a select is permanently not ready. Without nil-ing it, the next iteration would race: the timer's channel might still appear ready and we would fire on stale data. Nil-ing is the cleanest disable.

Cheat Sheet¶

// Trailing debounce: fire 300ms after last event.
deb := time.AfterFunc(300*time.Millisecond, fn)
// On event:
deb.Stop(); deb = time.AfterFunc(300*time.Millisecond, fn)

// Leading throttle: fire if 1s has elapsed.
if time.Since(last) >= time.Second {
    last = time.Now(); fn()
}

// Trailing throttle: ticker emits at most once per tick.
tick := time.NewTicker(time.Second); defer tick.Stop()
for {
    select {
    case v := <-in:  pending = v; hasPending = true
    case <-tick.C:   if hasPending { out <- pending; hasPending = false }
    case <-ctx.Done(): return
    }
}

// Channel-based debounce: timer + nil-channel disable.
var timer *time.Timer; var tc <-chan time.Time
for {
    select {
    case v := <-in:
        pending = v; hasPending = true
        if timer == nil { timer = time.NewTimer(d) } else { timer.Stop(); select { case <-timer.C: default: }; timer.Reset(d) }
        tc = timer.C
    case <-tc:
        if hasPending { out <- pending; hasPending = false }
        tc = nil
    case <-ctx.Done(): return
    }
}

Decision table¶

Self-Assessment Checklist¶

• I can state the difference between debounce and throttle in one sentence.
• I have written a working trailing debouncer using time.AfterFunc.
• I have written a working throttler using time.Ticker.
• I know why my goroutine must accept a context.Context or a done channel.
• I know what Stop-then-drain is and why we do it before Reset.
• I can explain why time.Tick (no New) is a leak.
• I can name three real product features served by debounce and three served by throttle.
• I know when to use the channel-based form and when to use the method-based form.
• I can recognise a captured-loop-variable bug in a debounce callback.
• I have run the test suite with go test -race -count=10.

Summary¶

A debouncer waits for silence; a throttler watches the clock. The simplest debouncer is a time.AfterFunc you Stop and reschedule on every event. The simplest throttler is a time.Ticker plus a single-slot channel. Both run in their own goroutine, both accept a context for cancellation, and both must be careful to clean up their timer when done. Real systems often layer them — debounce input, throttle output — and that layered design composes naturally with Go channels.

If you stop reading here you have enough to build a search-box debouncer, a log throttler, or a per-IP rate limit. The next file (middle.md) introduces leading-edge variants, the golang.org/x/time/rate library, and the design choices that come with real production traffic.

What You Can Build¶

• A debounced search box for a CLI or web app.
• A throttled logger that suppresses repeated errors.
• A config-file watcher that reloads only after the burst of write events ends.
• A throttle in front of a downstream API to stay under 10 RPS.
• A WebSocket message coalescer that emits at most 30 fps per peer.
• A document auto-saver that persists 500ms after the user stops typing.

Further Reading¶

• The Go time package: https://pkg.go.dev/time
• Bradfitz on time pitfalls: https://dave.cheney.net/tag/timers
• The Go runtime timer implementation: src/runtime/time.go in the Go source tree
• golang.org/x/time/rate: https://pkg.go.dev/golang.org/x/time/rate
• Russ Cox on Go concurrency patterns: "Go Concurrency Patterns" talk
• Lodash debounce documentation (for cross-language flavour): https://lodash.com/docs/#debounce

Related Topics¶

• 01-ticker — the time.Ticker primitive in detail
• 02-afterfunc — the time.AfterFunc primitive in detail
• 03-timer-leaks — how timer cleanup goes wrong and how to fix it
• 04-exponential-backoff — a sibling pattern for retry-with-rate-limit
• 09-pipelines (forthcoming) — composition of channel stages
• 06-context — context.Context for cancellation

Diagrams and Visual Aids¶

Debounce timeline¶

events    : E   E E   E       E      E
                                          ↓ (timer expires)
output    :                              F
            ←——— resets ———→ ← quiet →

Throttle timeline¶

clock     : T   T   T   T   T   T   T   T
events    : E E E E E E E E E E E E E E E E
output    : E       E       E       E
             (drops in between)

Token bucket¶

   refill rate R/sec
        ↓
   ┌────────┐
   │tokens  │  max capacity B
   │ • • •  │
   └───┬────┘
       ↓ event takes 1 token
       (or waits if empty)

Combined search box pipeline¶

keystrokes ─→ DEBOUNCE 300ms ─→ THROTTLE 500ms ─→ search()
              (collapse burst)  (cap rate)

Decision flowchart¶

Do you want "only the last value matters"?
   yes  → DEBOUNCE
   no   → Do you want "max N per second"?
          yes → THROTTLE
          no  → No rate-limiting needed

State machine diagram for debounce¶

        ┌───────────────────────────────┐
        │                               │
        ↓                               │
   ┌─────────┐  Trigger(v)        ┌───────────┐
   │  Idle   │ ─────────────────→ │  Pending  │
   │ timer=∅ │                    │ timer set │
   └─────────┘ ←──────────────────└───────────┘
                  timer expires
                  fire fn(latest)
                  reset timer to nil

In the Idle state the debouncer holds no timer; the next Trigger creates one. In the Pending state every subsequent Trigger resets the timer's countdown. Only the timer's expiration can transition back to Idle, and that transition is also when fn is invoked. Close is not shown but is a third state that forcibly drops to Stopped from either of the two.

State machine diagram for throttle¶

   ┌─────────┐   tick                ┌────────────┐
   │ Closed  │ ────────────────────→ │  Open      │
   │ (drop)  │                       │ (let one)  │
   └─────────┘ ←───────────────────  └────────────┘
                 event accepted

In Closed state events are dropped (or queued). The next tick from the underlying time.Ticker moves the throttle to Open for an instant — long enough to let one event through — and then back. The "instant" is conceptual; in code it is a single iteration of the select loop.

Memory model timeline of a debounce fire¶

goroutine A (caller)        goroutine B (debounce loop)        goroutine C (timer)

Trigger("x") ──────────────→ in <- "x"
                              ↓
                              pending = "x"
                              timer.Reset(d)
                                                 d elapses ────→ <-timer.C ready
                              ←──────────────────────────────────|
                              fn("x")
                                                                 ↑
                                                       runtime goroutine fires

Three goroutines participate. The caller never blocks (the in channel is buffered). The debounce loop owns the state. The runtime spawns a brief goroutine to deliver the timer signal — though for AfterFunc the runtime directly invokes the function and there is no intermediate channel.

Sequence chart: token bucket with burst¶

time:  0       1       2       3       4       5
bkt :  •••••   •••••   ••••    •••     ••••    •••
       (5)     (refill (1 evt) (1 evt) (refill (1 evt)
                +0,    consumed         +1)    consumed
                cap-5)

Five tokens at t=0 means we can serve five events instantly (the "burst"). After the burst, the bucket refills at the configured rate. This is the difference between token bucket and leaky bucket: token bucket allows the initial burst, leaky bucket does not.

Comparative latency chart¶

event arrival:    | | |    |        |
                  +0 +1 +2 +6       +11

trailing debounce 300ms:
  fires at +6+300=+306 (one fire only)

leading debounce 300ms:
  fires at +0 and +6+300=+306 (well, leading fires at +0 only if quiet preceded)

leading throttle 300ms:
  fires at +0, +6, +11 (each respects the 300ms cooldown from the previous fire)

trailing throttle 300ms (ticker):
  fires at +300, +600, +900, +1200 (regular grid; one event per slot, latest in slot)

Read this chart twice; it captures the actual behavioural differences between the four variants on the same input.

A guided rebuild from first principles¶

If everything above feels like a lot, it helps to rebuild the patterns from scratch in tiny steps. Let us start with the simplest possible "rate-limited print" and work upward.

Step 1: print all events¶

package main

import "fmt"

func main() {
    events := []string{"a", "b", "c", "d", "e"}
    for _, e := range events {
        fmt.Println(e)
    }
}

No rate limiting. Five lines of output, instant.

Step 2: pace with sleep¶

package main

import (
    "fmt"
    "time"
)

func main() {
    events := []string{"a", "b", "c", "d", "e"}
    for _, e := range events {
        fmt.Println(e)
        time.Sleep(200 * time.Millisecond)
    }
}

Still all five events, but spaced. Total runtime ~1 second.

Step 3: enforce a rate even when events come from somewhere else¶

In step 2 we own the loop. In real systems events arrive on a channel from a different goroutine. The pacing has to live in the consumer.

package main

import (
    "fmt"
    "time"
)

func main() {
    events := make(chan string, 10)
    go func() {
        for _, e := range []string{"a", "b", "c", "d", "e"} {
            events <- e
        }
        close(events)
    }()

    last := time.Time{}
    for e := range events {
        if !last.IsZero() && time.Since(last) < 200*time.Millisecond {
            time.Sleep(200*time.Millisecond - time.Since(last))
        }
        fmt.Println(e)
        last = time.Now()
    }
}

This is a blocking, lossless throttle written in 15 lines. Every event eventually prints, but no two within 200ms of each other. The consumer absorbs the rate-limiting work.

Step 4: switch to drop instead of block¶

last := time.Time{}
for e := range events {
    if !last.IsZero() && time.Since(last) < 200*time.Millisecond {
        continue
    }
    fmt.Println(e)
    last = time.Now()
}