Concurrent TTL Caches — Junior Level¶

Table of Contents¶

1. Introduction
2. Prerequisites
3. Glossary
4. Why a TTL Cache?
5. The Smallest Possible Cache
6. Adding a TTL
7. Making It Safe for Concurrency
8. Lazy Expiration
9. Active Expiration: a Sweep Goroutine
10. Stopping the Sweeper Cleanly
11. Get, Set, Delete in Detail
12. Returning Values Safely
13. Time: time.Now vs Monotonic
14. A Worked Walk-through: User Session Cache
15. Per-Entry TTLs
16. Generic Cache with Go Generics
17. Counting Hits and Misses
18. Sizing the Sweep Interval
19. Testing a TTL Cache
20. Race Detector and go test -race
21. Common First-Time Bugs
22. Mental Models
23. Real-World Analogies
24. Pros, Cons, and Trade-offs
25. Use Cases at the Junior Level
26. Clean-Code Considerations
27. Error Handling
28. Security Considerations
29. Performance Tips at the Junior Level
30. Best Practices
31. Edge Cases and Pitfalls
32. Common Misconceptions
33. Migrating From an Unsafe Cache
34. Comparing to Plain map, sync.Map, and Channels
35. Cheat Sheet
36. Self-Assessment Checklist
37. Test Yourself
38. Tricky Questions
39. Summary
40. What You Can Build
41. Further Reading
42. Related Topics
43. Diagrams & Visual Aids

Introduction¶

Focus: "What is a TTL cache? Why is it harder than a plain map? Show me the smallest working version."

A TTL cache is a key-value store where each entry has an expiration time. Once that time passes, the entry is no longer visible to readers — it has effectively been deleted, even if no goroutine actually removed it from memory. TTL stands for time-to-live: the amount of time an entry is considered alive.

You will meet TTL caches every time you want to:

• Avoid hitting a slow database for the same key over and over for the next 60 seconds
• Cache the result of an expensive computation for a few minutes
• Remember a user's authentication state for an hour without re-validating it on every request
• Hold a rate-limiter's "tokens" that should naturally decay
• Memoize an HTTP API response so a microservice doesn't drown its upstream

The "junior" version of this story is: a map[string]Entry, an sync.RWMutex, and a goroutine that occasionally wakes up to throw out dead entries. That is enough to handle most basic situations, and learning it well gives you the vocabulary needed for everything that follows. We will write that cache step by step, fix the bugs that beginners always introduce, and only then look at the real production designs.

After reading this file you will:

• Know what a TTL cache is and what Get, Set, and Delete mean in this context
• Be able to write a thread-safe cache with map + sync.RWMutex from memory
• Understand the difference between lazy and active eviction
• Be able to write a sweep goroutine that does not leak when the cache is destroyed
• Recognise the most common race conditions: lost updates, expired-then-resurrected, slow reader under writer
• Know why time.Now() is the right choice in Go but you must still be aware of monotonic vs wall-clock time
• Understand what a thundering herd on expiry is (we fix it properly at the middle level)

You do not need to know about sharded caches, ristretto, off-heap layout, or singleflight. Those come later.

Prerequisites¶

• Required: Go 1.21 or newer.
• Required: Comfort with map, slices, pointers, struct fields.
• Required: Basic understanding of goroutines and the go keyword.
• Required: Awareness that maps in Go are not safe for concurrent read+write — touching the same map from two goroutines without synchronisation crashes the program with a fatal "concurrent map writes" error.
• Helpful: Some exposure to sync.Mutex / sync.RWMutex.
• Helpful: Familiarity with time.Now(), time.Duration, time.After, and time.Ticker.

If you can write a function that reads from a map under a mutex, you are ready.

Glossary¶

Why a TTL Cache?¶

The first question every reviewer will ask is: "Why a cache at all?" The honest answer is: because some piece of data is expensive to obtain but cheap to remember for a while. Examples:

• A database call that takes 50 ms but returns the same answer for the next 60 seconds for 99% of users.
• A JWT verification that costs 2 ms of CPU but returns the same (userID, scopes) pair until the token expires.
• A DNS lookup that takes 30 ms but is valid for the duration of the TTL the resolver returned.
• An HTML rendering that takes 200 ms but does not change as long as the underlying article does not.

You could use a plain cache — a map without TTL — but then you face two problems:

1. Memory grows forever. Every key ever requested is held for the rest of the process's life.
2. You cannot reason about staleness. If the underlying data changes, the cache will happily return wrong answers until you restart.

TTL gives you both bounded memory (entries eventually fall out) and bounded staleness (the answer is at most ttl seconds out of date). That is the contract.

A TTL cache does not guarantee that data is exactly ttl seconds old — only that it is not older than ttl seconds. The actual staleness depends on the cache's internal clock and on how often the sweeper runs. We will see this in detail below.

The Smallest Possible Cache¶

Before TTL, before concurrency, before sweeping — start with the absolute minimum. A cache is a wrapper around a map. Here is the simplest version:

package cache

// SimpleCache is a minimal, non-thread-safe, non-expiring cache.
// Do NOT use this in concurrent code.
type SimpleCache struct {
    data map[string]string
}

func NewSimpleCache() *SimpleCache {
    return &SimpleCache{data: make(map[string]string)}
}

func (c *SimpleCache) Get(key string) (string, bool) {
    v, ok := c.data[key]
    return v, ok
}

func (c *SimpleCache) Set(key, value string) {
    c.data[key] = value
}

func (c *SimpleCache) Delete(key string) {
    delete(c.data, key)
}

This compiles and works in a single goroutine. It is also broken in three important ways:

1. No concurrency safety. Two goroutines calling Set simultaneously will crash with fatal error: concurrent map writes.
2. No expiration. Entries live forever.
3. No size limit. Memory grows without bound.

We will fix the first two in this file. The third — size-bounded eviction (LRU / LFU) — belongs to the next subsection.

Adding a TTL¶

To give each entry an expiration, store an Entry struct instead of a raw value:

package cache

import "time"

type entry struct {
    value      string
    expiresAt  time.Time
}

type TTLCache struct {
    data        map[string]entry
    defaultTTL  time.Duration
}

func NewTTLCache(defaultTTL time.Duration) *TTLCache {
    return &TTLCache{
        data:       make(map[string]entry),
        defaultTTL: defaultTTL,
    }
}

func (c *TTLCache) Set(key, value string) {
    c.data[key] = entry{
        value:     value,
        expiresAt: time.Now().Add(c.defaultTTL),
    }
}

func (c *TTLCache) Get(key string) (string, bool) {
    e, ok := c.data[key]
    if !ok {
        return "", false
    }
    if time.Now().After(e.expiresAt) {
        // Expired. Treat as missing.
        delete(c.data, key)
        return "", false
    }
    return e.value, true
}

func (c *TTLCache) Delete(key string) {
    delete(c.data, key)
}

Note the move from string to entry{value, expiresAt} and the new check inside Get. This is lazy eviction: we never remove the expired entry until somebody asks for it. That is fine for a single goroutine, but two problems remain:

• This is still not concurrency-safe.
• Keys that are written once and never read again will sit in memory forever.

We will tackle them one at a time.

Making It Safe for Concurrency¶

In Go, the map type is not safe for concurrent read+write. The runtime actively detects this and panics:

fatal error: concurrent map writes
fatal error: concurrent map read and map write

There are two practical ways to make a map-backed cache safe:

1. Wrap it in a mutex. Either sync.Mutex (simple, serialises everything) or sync.RWMutex (multiple concurrent readers, one writer).
2. Use sync.Map. A purpose-built concurrent map with different performance characteristics. We will see it at the middle level; it is not always faster than a mutex-protected map.

Start with sync.RWMutex. It is the right choice when reads vastly outnumber writes — which is true for almost every real cache.

package cache

import (
    "sync"
    "time"
)

type entry struct {
    value     string
    expiresAt time.Time
}

type TTLCache struct {
    mu         sync.RWMutex
    data       map[string]entry
    defaultTTL time.Duration
}

func NewTTLCache(defaultTTL time.Duration) *TTLCache {
    return &TTLCache{
        data:       make(map[string]entry),
        defaultTTL: defaultTTL,
    }
}

func (c *TTLCache) Set(key, value string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.data[key] = entry{
        value:     value,
        expiresAt: time.Now().Add(c.defaultTTL),
    }
}

func (c *TTLCache) Get(key string) (string, bool) {
    c.mu.RLock()
    e, ok := c.data[key]
    c.mu.RUnlock()

    if !ok {
        return "", false
    }
    if time.Now().After(e.expiresAt) {
        // Expired — drop it under a write lock.
        c.mu.Lock()
        // Re-check under write lock; somebody may have refreshed it.
        if cur, ok := c.data[key]; ok && time.Now().After(cur.expiresAt) {
            delete(c.data, key)
        }
        c.mu.Unlock()
        return "", false
    }
    return e.value, true
}

func (c *TTLCache) Delete(key string) {
    c.mu.Lock()
    delete(c.data, key)
    c.mu.Unlock()
}

There is a subtlety here worth pausing on. We read under RLock, then if the entry is expired we upgrade by releasing the read lock and acquiring the write lock. Between those two operations, another goroutine might have already overwritten the entry with a fresh value. That is why we re-check under the write lock before deleting. If you skip the re-check you can lose updates: thread A finds the entry expired, but before A deletes it, thread B writes a fresh entry — A then deletes B's fresh entry. This pattern, "re-check under the stronger lock," appears all over concurrent programming.

Why don't we hold the write lock the whole time? Because almost all calls are hits — the entry is live, no deletion needed. Holding the write lock for every Get would serialise the entire cache and destroy throughput. The read lock allows many concurrent hits.

Lazy Expiration¶

The cache we just built does lazy expiration: the only way an entry leaves memory is

1. A reader looks it up, finds it expired, and deletes it.
2. A writer overwrites it.
3. Someone calls Delete.

Lazy expiration is appealing for its simplicity — no extra goroutines, no scheduling decisions. But it has a serious shortcoming: keys that are inserted and never read again live forever.

Consider a cache that holds session tokens. Users log in, the token goes into the cache, the user closes their browser and never comes back. With pure lazy eviction, the entry stays in memory until the process restarts. After a month, you have millions of dead session entries occupying gigabytes of RAM.

Pure lazy is therefore appropriate only when:

• Every key gets re-read often (e.g. you cache a small set of hot keys).
• The cache has another memory bound (e.g. an LRU on top, which is the next subsection's topic).
• Total memory is bounded by the key space (e.g. you cache all user records and there are at most 10,000 users).

For any realistic backend cache, you need active eviction — a sweep goroutine.

Active Expiration: a Sweep Goroutine¶

A sweeper is a background goroutine that wakes up every so often, walks the cache, and deletes entries whose expiresAt is in the past. The simplest implementation uses a time.Ticker:

package cache

import (
    "sync"
    "time"
)

type entry struct {
    value     string
    expiresAt time.Time
}

type TTLCache struct {
    mu         sync.RWMutex
    data       map[string]entry
    defaultTTL time.Duration

    stop chan struct{}
}

func NewTTLCache(defaultTTL, sweepInterval time.Duration) *TTLCache {
    c := &TTLCache{
        data:       make(map[string]entry),
        defaultTTL: defaultTTL,
        stop:       make(chan struct{}),
    }
    go c.sweepLoop(sweepInterval)
    return c
}

func (c *TTLCache) sweepLoop(interval time.Duration) {
    ticker := time.NewTicker(interval)
    defer ticker.Stop()

    for {
        select {
        case <-ticker.C:
            c.sweep()
        case <-c.stop:
            return
        }
    }
}

func (c *TTLCache) sweep() {
    now := time.Now()
    c.mu.Lock()
    defer c.mu.Unlock()
    for k, e := range c.data {
        if now.After(e.expiresAt) {
            delete(c.data, k)
        }
    }
}

func (c *TTLCache) Close() {
    close(c.stop)
}

Three things to notice immediately.

First — the sweeper holds the write lock for the entire pass. If the map has a million entries, no Get and no Set can proceed until the sweep finishes. On a million-entry map that may be 50–200 ms of stall. That is acceptable for a learning project; we will fix it at the middle level by sweeping in batches.

Second — delete during range is safe in Go. The language specification explicitly permits removing entries from a map you are ranging over. You may not safely add during iteration (the new keys may or may not appear in the rest of the range), but delete is fine.

Third — Close must be called to stop the sweeper. If you forget, the sweeper goroutine lives until the process dies — a textbook goroutine leak. The sweeper holds a reference to the cache, which holds a reference to its map; together they prevent the whole structure from being garbage collected, even if no other goroutine has a handle to it. We will harden this below.

Stopping the Sweeper Cleanly¶

The close(c.stop) pattern is the idiomatic way to broadcast a stop signal to one or many goroutines. But there are two pitfalls.

Pitfall 1: closing twice¶

c.Close() // first call closes c.stop — fine
c.Close() // second call panics: "close of closed channel"

Either document "call Close at most once" or guard with sync.Once:

import "sync"

type TTLCache struct {
    // ... other fields ...
    stop     chan struct{}
    stopOnce sync.Once
}

func (c *TTLCache) Close() {
    c.stopOnce.Do(func() { close(c.stop) })
}

sync.Once makes Close idempotent. For a real product, this is usually worth it.

Pitfall 2: the sweeper is mid-pass when Close is called¶

If the sweeper is currently inside the for k, e := range c.data loop with the lock held, close(c.stop) only marks the signal. The sweeper will finish the current pass, release the lock, and then select the stop case. That is fine for correctness, but if you want Close to be synchronous you need to wait for the sweeper to exit:

type TTLCache struct {
    // ... other fields ...
    stop     chan struct{}
    stopOnce sync.Once
    done     chan struct{}
}

func NewTTLCache(defaultTTL, sweepInterval time.Duration) *TTLCache {
    c := &TTLCache{
        data:       make(map[string]entry),
        defaultTTL: defaultTTL,
        stop:       make(chan struct{}),
        done:       make(chan struct{}),
    }
    go func() {
        defer close(c.done)
        c.sweepLoop(sweepInterval)
    }()
    return c
}

func (c *TTLCache) Close() {
    c.stopOnce.Do(func() { close(c.stop) })
    <-c.done
}

Now Close returns only after the sweeper has actually exited. That is also the right model for testing — your test can Close and then assert that no further calls into the cache see a running sweeper.

Get, Set, Delete in Detail¶

Now we have a working cache. Let's walk through each operation carefully, because at the junior level the order of operations matters more than the precise data structure.

Set¶

func (c *TTLCache) Set(key, value string) {
    c.mu.Lock()
    c.data[key] = entry{
        value:     value,
        expiresAt: time.Now().Add(c.defaultTTL),
    }
    c.mu.Unlock()
}

Decisions made here:

• Time captured inside the lock. This is conservative but cheap. If two goroutines call Set "simultaneously," whichever the runtime serialises second has the later expiresAt. That is the natural and expected behaviour.
• Overwrites are unconditional. A second Set of the same key replaces the value and extends the expiration. This is sometimes called "refresh on write."

A variant that some people want is "Set if absent or expired." That is SetNX-style semantics, useful for things like distributed locks. We will write it explicitly because the naive form has a race:

// WRONG: race between Get and Set.
func (c *TTLCache) SetIfAbsent_BUGGY(key, value string) bool {
    if _, ok := c.Get(key); ok {
        return false
    }
    c.Set(key, value) // another goroutine may have set it in between
    return true
}

// CORRECT: do the check inside a single locked region.
func (c *TTLCache) SetIfAbsent(key, value string) bool {
    c.mu.Lock()
    defer c.mu.Unlock()
    if e, ok := c.data[key]; ok && time.Now().Before(e.expiresAt) {
        return false
    }
    c.data[key] = entry{
        value:     value,
        expiresAt: time.Now().Add(c.defaultTTL),
    }
    return true
}

This is the classic check-then-act race. Always do both steps under the same lock.

Get¶

func (c *TTLCache) Get(key string) (string, bool) {
    c.mu.RLock()
    e, ok := c.data[key]
    c.mu.RUnlock()

    if !ok {
        return "", false
    }
    if time.Now().After(e.expiresAt) {
        // Expired. We could delete here, but the sweeper will get it eventually.
        return "", false
    }
    return e.value, true
}

Note that we do not delete the expired entry on miss. Why?

• Deleting requires upgrading to a write lock, which is expensive.
• The sweeper will pick it up soon enough.
• The performance of Get is the most important metric of the entire cache — keep it cheap.

If you want eager deletion (some applications do, especially when entries are very large), you can keep the deleting version from earlier. There is no single right answer; both are common.

Delete¶

func (c *TTLCache) Delete(key string) {
    c.mu.Lock()
    delete(c.data, key)
    c.mu.Unlock()
}

Always under write lock. Note that delete of a non-existent key is a no-op in Go — it does not panic.

A subtlety: should Delete report whether the key was present? Some APIs do:

func (c *TTLCache) Delete(key string) (existed bool) {
    c.mu.Lock()
    defer c.mu.Unlock()
    if _, ok := c.data[key]; ok {
        delete(c.data, key)
        return true
    }
    return false
}

This is occasionally useful for caller-side metrics. Make the API decision once and stick to it.

Returning Values Safely¶

Our cache stores string, which is immutable in Go — a returned string cannot be mutated by the caller. But what if the value is a []byte, a map, or a pointer to a mutable struct?

type Entry struct {
    body []byte
}

func (c *Cache) Get(k string) (Entry, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    e, ok := c.data[k]
    return e, ok // returns a COPY of Entry, but the slice header still points to the same backing array
}

The caller now holds a slice that shares memory with the cached value. If the caller does e.body[0] = 'x', they have mutated the cache too. Even worse, two goroutines that both received the slice are now racing each other through the cache.

Three defences:

1. Document immutability. "Do not mutate the returned slice. If you need to mutate, copy first." Cheap but error-prone.
2. Defensive copy. Get copies the slice before returning. Costs a heap allocation per call.
3. Use immutable types. string for bytes, value types for structs, no shared maps.

At the junior level, prefer immutable types. As you grow into the middle and senior levels you will learn when defensive copies are worth their cost.

Time: time.Now vs Monotonic¶

time.Now() in Go returns a time.Time that carries two readings simultaneously: the wall clock (calendar time) and a monotonic reading. Comparisons via After, Before, Sub use the monotonic reading when both operands have one. That means our TTL cache is naturally robust against wall-clock jumps — if an NTP daemon adjusts the system clock by 5 minutes, our TTL math still works correctly, because expiresAt.Sub(time.Now()) uses monotonic.

There is exactly one case where you lose monotonic time in Go:

• Serialising and deserialising a time.Time (e.g. via JSON, gob) strips the monotonic reading.
• Calling .Round(0) explicitly strips it.

For an in-memory cache that never serialises its expiresAt field, monotonic time works without you having to think about it. That is one fewer thing to get wrong.

If you find yourself storing expiresAt as a Unix timestamp (int64), you have given up monotonic time and are now exposed to wall-clock jumps. That is sometimes the right trade — for caches that span across process restarts via shared memory or external storage — but be aware.

A small mental exercise: imagine the system clock jumps forward by 1 hour because of a daylight-saving correction. What happens to a TTL cache that uses time.Now() directly versus one that stores int64 Unix timestamps?

• time.Now() version: the monotonic clock did not jump, so After/Before still behave correctly; nothing observable happens.
• int64 Unix timestamp version: every entry whose stored expiry is more than 1 hour in the future is unaffected, but every entry whose stored expiry was less than 1 hour from now is now considered expired. The cache appears to "flush" itself.

Now imagine the clock jumps backwards by 1 hour:

• time.Now() version: still nothing.
• int64 Unix timestamp version: entries that should have expired in the next hour are now "alive" for an extra hour. Worse, you might re-insert keys with shorter TTLs than the existing entries — the cache stops respecting "last write wins" temporally.

This is why, for in-process caches, idiomatic Go uses time.Time and lets the runtime hide the monotonic-clock plumbing. Only step outside that abstraction when the cache crosses a process boundary.

A Worked Walk-through: User Session Cache¶

Theory is fine, but the cache only earns its keep when you wire it into a real component. Let us walk through a realistic use case end-to-end: caching authenticated user sessions in an HTTP server.

The story: clients present a session token as a cookie. Validating the token requires querying the auth database (about 5 ms per call). The token is valid for 30 minutes after issuance. We want every request after the first to skip the database call.

package session

import (
    "errors"
    "sync"
    "time"
)

type Session struct {
    UserID   int64
    Scopes   []string
    IssuedAt time.Time
}

type Store interface {
    Lookup(token string) (Session, error)
}

type Cache struct {
    mu    sync.RWMutex
    data  map[string]entry
    ttl   time.Duration
    store Store

    stop     chan struct{}
    stopOnce sync.Once
    done     chan struct{}
}

type entry struct {
    sess      Session
    expiresAt time.Time
}

var ErrInvalid = errors.New("invalid token")

func New(store Store, ttl, sweep time.Duration) *Cache {
    c := &Cache{
        data:  make(map[string]entry),
        ttl:   ttl,
        store: store,
        stop:  make(chan struct{}),
        done:  make(chan struct{}),
    }
    go func() {
        defer close(c.done)
        c.sweepLoop(sweep)
    }()
    return c
}

func (c *Cache) Get(token string) (Session, error) {
    c.mu.RLock()
    e, ok := c.data[token]
    c.mu.RUnlock()
    if ok && time.Now().Before(e.expiresAt) {
        return e.sess, nil
    }
    // Cache miss — call the store.
    sess, err := c.store.Lookup(token)
    if err != nil {
        return Session{}, err
    }
    c.mu.Lock()
    c.data[token] = entry{sess: sess, expiresAt: time.Now().Add(c.ttl)}
    c.mu.Unlock()
    return sess, nil
}

func (c *Cache) Invalidate(token string) {
    c.mu.Lock()
    delete(c.data, token)
    c.mu.Unlock()
}

func (c *Cache) sweepLoop(interval time.Duration) {
    t := time.NewTicker(interval)
    defer t.Stop()
    for {
        select {
        case <-t.C:
            c.sweep()
        case <-c.stop:
            return
        }
    }
}

func (c *Cache) sweep() {
    now := time.Now()
    c.mu.Lock()
    for k, e := range c.data {
        if now.After(e.expiresAt) {
            delete(c.data, k)
        }
    }
    c.mu.Unlock()
}

func (c *Cache) Close() {
    c.stopOnce.Do(func() { close(c.stop) })
    <-c.done
}

Five things to notice about this real-world shape:

1. The cache is a layer over an interface (Store). Tests can supply a stub Store. Production wires in the real database. This is the idiomatic Go separation of concerns.
2. Get does the underlying call on miss. That couples the cache to the store, which is fine for a junior implementation but is what a senior would extract into a separate "loader" function and protect with singleflight.
3. Invalidate is exposed so the application can throw out a session on logout, password change, or admin action.
4. Close returns synchronously so a graceful shutdown can wait for the sweeper before letting the process exit.
5. Get may insert into the map under the write lock, even after seeing a miss under the read lock. This is the classic "RLock for hot path, Lock for cold path" pattern. It is correct here because we re-fetch from the store regardless — there is no decision to skip work based on stale state.

Now imagine 1,000 concurrent requests for the same expired token. All 1,000 take the slow path and all 1,000 hit the database. That is the thundering herd problem, and the fix is single-flight, which we save for middle.md.

Per-Entry TTLs¶

Our cache assumed every entry has the same TTL. Real systems often want different keys to live for different amounts of time:

• Successful DNS lookups: TTL provided by the server, usually 60–3600 s.
• Failed DNS lookups: TTL fixed at 5 s — you do not want to keep punishing the server but you also do not want to cache a typo forever.
• Auth tokens: TTL = token's remaining lifetime, not a global default.

The easiest way is to let Set take a TTL argument:

func (c *TTLCache) SetWithTTL(key, value string, ttl time.Duration) {
    c.mu.Lock()
    c.data[key] = entry{
        value:     value,
        expiresAt: time.Now().Add(ttl),
    }
    c.mu.Unlock()
}

func (c *TTLCache) Set(key, value string) {
    c.SetWithTTL(key, value, c.defaultTTL)
}

The sweeper does not change at all — it just inspects each entry's stored expiresAt. This is one of the nice properties of expiration-time rather than duration: per-entry TTLs are "free."

You can also pass 0 to mean "no expiration":

func (c *TTLCache) SetForever(key, value string) {
    c.mu.Lock()
    c.data[key] = entry{value: value} // expiresAt = zero
    c.mu.Unlock()
}

func (c *TTLCache) Get(key string) (string, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    e, ok := c.data[key]
    if !ok {
        return "", false
    }
    if !e.expiresAt.IsZero() && time.Now().After(e.expiresAt) {
        return "", false
    }
    return e.value, true
}

Be careful: if you mix 0-TTL entries with active eviction, the sweeper must skip them too:

func (c *TTLCache) sweep() {
    now := time.Now()
    c.mu.Lock()
    for k, e := range c.data {
        if !e.expiresAt.IsZero() && now.After(e.expiresAt) {
            delete(c.data, k)
        }
    }
    c.mu.Unlock()
}

Forgetting that check is a fun bug — the sweeper happily deletes every "forever" entry on the next tick, because the zero Time is in the distant past.

Generic Cache with Go Generics¶

Real applications cache more than strings. Since Go 1.18 you can write a single cache type that works for any value type, using type parameters:

package cache

import (
    "sync"
    "time"
)

type entry[V any] struct {
    value     V
    expiresAt time.Time
}

type TTLCache[V any] struct {
    mu         sync.RWMutex
    data       map[string]entry[V]
    defaultTTL time.Duration

    stop     chan struct{}
    stopOnce sync.Once
    done     chan struct{}
}

func New[V any](defaultTTL, sweepInterval time.Duration) *TTLCache[V] {
    c := &TTLCache[V]{
        data:       make(map[string]entry[V]),
        defaultTTL: defaultTTL,
        stop:       make(chan struct{}),
        done:       make(chan struct{}),
    }
    go func() {
        defer close(c.done)
        c.sweepLoop(sweepInterval)
    }()
    return c
}

func (c *TTLCache[V]) Get(key string) (V, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    e, ok := c.data[key]
    if !ok || time.Now().After(e.expiresAt) {
        var zero V
        return zero, false
    }
    return e.value, true
}

func (c *TTLCache[V]) Set(key string, value V) {
    c.mu.Lock()
    c.data[key] = entry[V]{value: value, expiresAt: time.Now().Add(c.defaultTTL)}
    c.mu.Unlock()
}

func (c *TTLCache[V]) Delete(key string) {
    c.mu.Lock()
    delete(c.data, key)
    c.mu.Unlock()
}

func (c *TTLCache[V]) sweepLoop(interval time.Duration) {
    t := time.NewTicker(interval)
    defer t.Stop()
    for {
        select {
        case <-t.C:
            c.sweep()
        case <-c.stop:
            return
        }
    }
}

func (c *TTLCache[V]) sweep() {
    now := time.Now()
    c.mu.Lock()
    for k, e := range c.data {
        if now.After(e.expiresAt) {
            delete(c.data, k)
        }
    }
    c.mu.Unlock()
}

func (c *TTLCache[V]) Close() {
    c.stopOnce.Do(func() { close(c.stop) })
    <-c.done
}

Now the same code caches sessions, integers, or any struct:

sessions := cache.New[Session](30*time.Minute, time.Minute)
counts   := cache.New[int](time.Minute, 5*time.Second)
records  := cache.New[*User](time.Hour, time.Minute)

Note *User rather than User: caching pointers avoids copying large structs but exposes you to the "returned-value-is-mutable" trap from earlier. Choose with intention.

Generics do not solve concurrency problems — every fix you learned for the string-typed version applies unchanged. But they do remove the need to maintain six near-identical caches for six different value types.

Counting Hits and Misses¶

Once you have a cache running in production, the first question your team will ask is: "What is the hit ratio?" If the answer is 5%, the cache is just slowing things down (extra map look-ups, extra memory, extra goroutine, no benefit). If the answer is 95%, you have probably amortised the underlying call by 20×.

Counting hits and misses is the lightest possible piece of observability and you should always add it. Use sync/atomic for the counters so that you do not pay a mutex cost on every lookup:

import "sync/atomic"

type TTLCache struct {
    // ... existing fields ...
    hits   atomic.Uint64
    misses atomic.Uint64
}

func (c *TTLCache) Get(key string) (string, bool) {
    c.mu.RLock()
    e, ok := c.data[key]
    c.mu.RUnlock()

    if !ok || time.Now().After(e.expiresAt) {
        c.misses.Add(1)
        return "", false
    }
    c.hits.Add(1)
    return e.value, true
}

func (c *TTLCache) Stats() (hits, misses uint64) {
    return c.hits.Load(), c.misses.Load()
}

That is two extra atomic operations per Get. On a modern CPU each is a few nanoseconds — negligible compared to the map lookup.

Two warnings:

• Do not use a Mutex to protect counters. That would add a 30–60 ns lock acquisition to every Get and serialise the cache.
• Atomic counters are not consistent snapshots. hits.Load() and misses.Load() are read at slightly different instants. You may compute a ratio that "exceeds 100%" by a tiny fraction if you sample at the wrong moment. For monitoring this is irrelevant; for tests it is a flake.

Beyond hit/miss, useful counters at the junior level include:

• Number of expired-on-read events (entries Get found expired before the sweeper got to them).
• Number of sweep passes performed.
• Number of entries removed by the last sweep.
• Number of entries currently in the cache.

Add them sparingly; each adds a small cost and visual noise. We will discuss richer observability in the senior and professional files.

Sizing the Sweep Interval¶

How often should the sweeper run? Too rarely, and dead entries accumulate. Too often, and the sweeper steals lock time from real readers.

A reasonable starting heuristic: sweepInterval = ttl / 5, but never less than 100 ms and rarely more than a minute. The factor of 5 means that, on average, an expired entry lives an extra 10% of its TTL before being swept, which is usually small enough to ignore.

ttl = 60s    -> sweep every 12s
ttl = 300s   -> sweep every 60s (clipped from 60s)
ttl = 5s     -> sweep every 1s
ttl = 200ms  -> sweep every 100ms (clipped lower bound)

For very small TTLs (say, sub-second), a fixed sweeper is the wrong design — you want the data structure to know when the next expiration is (a heap or timer-wheel, covered at the middle level). At the junior level just pick a sweepInterval less than or equal to ttl/2 and accept some waste.

A second knob is how much work per sweep. A naive sweep visits every entry; that is O(N) per pass. For a million-entry cache, that may be 50 ms of lock time. At the middle level you will see batched and time-budgeted sweepers; for now, expect that very large junior caches will stall under sweep load.

Testing a TTL Cache¶

Tests for a TTL cache fall into three buckets:

1. Functional tests. Set/Get/Delete behave as documented.
2. TTL tests. Entries expire when expected.
3. Concurrency tests. No races, no deadlocks, no leaks.

Functional tests¶

func TestSetGet(t *testing.T) {
    c := NewTTLCache(time.Minute, time.Second)
    defer c.Close()

    c.Set("k", "v")
    v, ok := c.Get("k")
    if !ok || v != "v" {
        t.Fatalf("expected v, got %v ok=%v", v, ok)
    }
}

func TestDelete(t *testing.T) {
    c := NewTTLCache(time.Minute, time.Second)
    defer c.Close()

    c.Set("k", "v")
    c.Delete("k")
    if _, ok := c.Get("k"); ok {
        t.Fatal("expected miss after Delete")
    }
}

TTL tests¶

The interesting question: how do you test "entry expires after 50 ms" without making tests slow?

• Option A: use real time, with a small TTL. Tests take 100 ms each.
• Option B: inject a clock.

Real time is acceptable when TTLs are short, but it makes tests inherently flaky on slow CI. Injecting a clock is more work up front but pays off:

type clock interface {
    Now() time.Time
}

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

type fakeClock struct {
    mu  sync.Mutex
    t   time.Time
}
func (f *fakeClock) Now() time.Time {
    f.mu.Lock()
    defer f.mu.Unlock()
    return f.t
}
func (f *fakeClock) Advance(d time.Duration) {
    f.mu.Lock()
    f.t = f.t.Add(d)
    f.mu.Unlock()
}

Then pass the clock into NewTTLCache and use c.clock.Now() everywhere. In tests you create a fakeClock, advance it past the TTL, and assert the entry is gone.

Be aware that you cannot fake out time.Ticker this way — that requires another abstraction. At the junior level, accept that the sweep portion of the cache is hard to fully fake-time, and rely on small real TTLs for sweep-specific tests.

Concurrency tests¶

func TestConcurrent(t *testing.T) {
    c := NewTTLCache(time.Second, 100*time.Millisecond)
    defer c.Close()

    var wg sync.WaitGroup
    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            key := fmt.Sprintf("k%d", id%10)
            for j := 0; j < 1000; j++ {
                c.Set(key, "v")
                c.Get(key)
            }
        }(i)
    }
    wg.Wait()
}

Run with -race. If the cache is correctly synchronised, the test passes silently. If you forgot a lock somewhere, the race detector will tell you exactly where the racy reads and writes happened.

Race Detector and go test -race¶

go run -race, go test -race, go build -race — all enable Go's built-in race detector. It instruments your binary to track memory accesses across goroutines and report any pair that:

• Are unsynchronised by mutexes, channels, atomics, or sync.Once,
• Touch the same memory address,
• And at least one of them is a write.

For a TTL cache you should be in the habit of running every test under -race because almost all the interesting bugs are race conditions invisible without it.

Costs of -race:

• 5–10× slower
• 5–10× more memory
• Larger binary

That is why you do not ship a -race binary to production. But every code path in your test suite should run under -race at least once per CI build.

A subtle point: the race detector only finds races that actually fire during a particular execution. Some races sit dormant for hours and only trigger under load. So -race greens up "no race here" but does not prove the code is race-free in the general sense. Pair -race with stress tests that schedule many goroutines doing many operations.

Common First-Time Bugs¶

Here are the bugs we see again and again in junior code reviews.

Bug 1: forgetting to unlock¶

func (c *Cache) Get(k string) (string, bool) {
    c.mu.RLock()
    e, ok := c.data[k]
    if !ok {
        return "", false   // RLock leaked!
    }
    c.mu.RUnlock()
    return e.value, true
}

Fix: use defer:

func (c *Cache) Get(k string) (string, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    e, ok := c.data[k]
    if !ok {
        return "", false
    }
    return e.value, true
}

Or release before every return. defer is safer.

Bug 2: writing the map while holding only the read lock¶

func (c *Cache) GetOrCompute(k string, compute func() string) string {
    c.mu.RLock()
    defer c.mu.RUnlock()
    if e, ok := c.data[k]; ok {
        return e.value
    }
    c.data[k] = entry{value: compute()} // RACE: write under RLock
    return c.data[k].value
}

sync.RWMutex does not detect this. The Go runtime will eventually panic with "concurrent map writes" once a second goroutine actually writes. Always upgrade to Lock().

Bug 3: holding the lock across a slow call¶

func (c *Cache) GetOrFetch(k string) string {
    c.mu.Lock()
    defer c.mu.Unlock()
    if e, ok := c.data[k]; ok {
        return e.value
    }
    v := slowDatabaseCall(k)         // holds the lock for 200 ms!
    c.data[k] = entry{value: v, expiresAt: time.Now().Add(time.Minute)}
    return v
}

While one goroutine waits on slowDatabaseCall, every other goroutine is blocked. The proper pattern uses singleflight (middle level) or releases the lock around the slow call (and accepts that two goroutines may compute the same value once).

Bug 4: capturing the loop variable in the sweeper¶

In Go versions before 1.22 this was a real bug. From 1.22 the language semantics changed and each iteration gets its own variable, but you may still see legacy code:

for k, e := range c.data {
    go func() {
        if time.Now().After(e.expiresAt) {
            c.mu.Lock()
            delete(c.data, k) // k and e are the SAME variable in pre-1.22 Go
            c.mu.Unlock()
        }
    }()
}

In modern Go this works. In old Go it deletes the wrong keys. Always pin the version your project requires.

Bug 5: sweep deadlock¶

If your sweeper holds the cache lock and then somehow calls back into the cache, you will deadlock with yourself.

func (c *Cache) sweep() {
    c.mu.Lock()
    defer c.mu.Unlock()
    for k := range c.data {
        if c.isExpired(k) { // isExpired also tries to take c.mu — deadlock
            delete(c.data, k)
        }
    }
}

Fix: do the comparison inline without re-entering any cache method, or use a sync.Mutex with explicit unlocking patterns.

Bug 6: not stopping the sweeper¶

func someHandler() {
    c := NewTTLCache(time.Minute, time.Second)
    // ... use c ...
    return // c goes out of scope but the sweeper goroutine still runs forever
}

Always defer c.Close() or wire the cache into a longer-lived component.

Bug 7: zero-value Time treated as not-expired¶

type entry struct {
    value     string
    expiresAt time.Time // zero by default
}

func (c *Cache) Set(k, v string) {
    c.data[k] = entry{value: v} // forgot to set expiresAt!
}

// Get treats e.expiresAt == zero as: time.Now().After(time.Time{}) → true
// so the entry is immediately considered expired.

This bug is sneaky because the cache "works" — every Set followed by Get returns a miss because the entry expired the moment it was inserted. Always test that a freshly inserted entry is actually retrievable.

Bug 8: clock skew between Set and Get¶

expiresAt := time.Now().Add(ttl)
// ... 100 ms pass ...
if time.Now().After(expiresAt) { ... } // uses monotonic time → correct

Fine in normal Go because time.Now() is monotonic. But if you serialised expiresAt to JSON and back, monotonic is stripped — and a system-clock adjustment may now make After lie.

Bug 9: the sweeper outlives the cache¶

A subtle goroutine leak. Consider:

func makeCache() *TTLCache {
    c := NewTTLCache(time.Minute, time.Second)
    return c // caller never calls Close
}

func handle() {
    c := makeCache()
    use(c)
    // c goes out of scope — but the sweeper still references the map.
}

The sweeper goroutine holds a reference to c (via the method receiver in sweepLoop). Therefore c is not eligible for garbage collection, even after the caller drops its last reference. The map, the mutex, the entries, and the sweeper itself all leak — for the life of the process. This is one of the easiest ways to leak goroutines in a long-running service.

Fix: always wire Close() into a deferred call, a shutdown hook, or a parent component's Close.

Bug 10: assuming Get is purely a read¶

// In a benchmark, this line shows up as "expensive":
v, ok := c.Get(key)

Why? Because our Get might take a write lock (the upgrade path when the entry is expired). If 30% of Get calls hit an expired entry, the cache is effectively serialised 30% of the time. The benchmark mysteriously shows that "reads" are slower than expected.

Fix at the junior level: do not delete in Get — let the sweeper handle it. The miss penalty is a wasted lookup, not a serialisation.

Bug 11: time.After in the sweep loop, not time.NewTicker¶

for {
    select {
    case <-time.After(interval):
        c.sweep()
    case <-c.stop:
        return
    }
}

time.After allocates a new timer on every iteration and never reclaims it until it fires. If c.stop fires first, the pending timer leaks for interval. For short intervals this is harmless; for long intervals (minutes) under high Close churn (e.g. in tests) this matters. Use time.NewTicker and defer ticker.Stop().

Bug 12: Goroutines launched per Set¶

A creative beginner sometimes writes:

func (c *Cache) Set(k, v string) {
    c.mu.Lock()
    c.data[k] = entry{value: v, expiresAt: time.Now().Add(c.ttl)}
    c.mu.Unlock()
    go func() {
        time.Sleep(c.ttl)
        c.Delete(k) // self-expiring entry!
    }()
}

It "works" — but it spawns a goroutine per entry. A cache with 10,000 entries has 10,000 sleeping goroutines. A cache with 10,000,000 entries has 10,000,000 goroutines — and your process is out of memory. The whole point of a sweeper is to use one goroutine for the entire cache.

Mental Models¶

Model 1: a sieve¶

Picture the cache as a sieve. New entries fall in from above with a stopwatch attached. Some entries are retrieved (a reader picks them out, checks the stopwatch, accepts or rejects them). The rest stay in the sieve until the sweeper passes through with a magnet that pulls out everything whose stopwatch has hit zero.

This model makes it obvious that there are two ways an entry leaves the sieve: a reader removes it, or the sweeper does. If neither happens, the entry stays forever.

Model 2: a sliding window of stickies¶

Each entry is a sticky note with a date written on it. Every so often, a janitor walks through and removes any stickies whose date is in the past. Readers look at the stickies; if they find an old one, they may also throw it out themselves. The janitor's pace and the readers' attention together determine how many old stickies pile up.

Model 3: two pipelines that cross¶

Readers and writers form one pipeline: random arrivals from many goroutines, all touching the same map. The sweeper forms a second pipeline: a slow, periodic process that contends with the first. The interesting questions are all about the interaction between these two pipelines — what happens when the sweeper holds the lock while readers wait, what happens when readers find an entry the sweeper is about to delete, what happens at shutdown.

Real-World Analogies¶

Concrete analogies often beat formal definitions when you are reasoning about a concurrent data structure for the first time.

A library returns shelf. Books arrive in a hurry, get stacked on a returns shelf, and patrons grab them back when they want them again. Once a week, a librarian walks past and removes anything that has been sitting too long. The "TTL" is "how long a book may sit on the shelf"; the "sweep" is the librarian's weekly walk. Patrons (readers) can also throw a book in the discard bin if they see it is too dusty.

A milk fridge. Each carton has a "best before" date. Customers check the date when they pick one up (lazy eviction). A staff member also walks through periodically and tosses cartons past their date (active eviction). When the fridge gets crowded, additional rules kick in — recency-based eviction, popularity-based eviction — which is the LRU/LFU world from the next subsection.

A DNS cache. Probably the canonical TTL example: when a DNS server answers a query, it tells the resolver how long the answer may be reused. The resolver stores the answer with that expiration and serves later identical queries from cache until expiry. Once expired, the next query forces a fresh round-trip. Real DNS resolvers add jitter, negative caching, prefetching — all topics for the senior and professional pages.

A token machine in a queue system. When you take a number at the deli, the number is valid for some duration; if you walk away, the number is forfeited and the staff calls the next person. The machine sweeps for forfeited numbers and reuses them.

Bus arrival predictions. "Next bus in 7 minutes." That estimate is cached for ~30 s on the transit app. After 30 s, the app fetches a fresh prediction. If many users open the app within the same second, the app should bundle their fetches together — singleflight.

Pros, Cons, and Trade-offs¶

Pros¶

• Simplicity. A map[string]entry plus a mutex plus a sweeper is fewer than 100 lines of Go.
• Predictable staleness. Entries are at most ttl + sweepInterval out of date.
• Memory bounded by entry lifetime. Even without an explicit size cap, RAM stops growing eventually.
• No external dependencies. Pure standard library at the junior level.

Cons¶

• Global mutex. Every operation contends with every other. For high-throughput services this becomes a bottleneck.
• No size limit. A flood of unique keys can fill RAM faster than the sweeper can clear them.
• Thundering herds on expiry. Single hot key expires → all readers miss simultaneously → upstream is hammered.
• Sweep stalls. A sweep that holds the lock for 100 ms while traversing a million-entry map stops all readers for 100 ms. p99 latency suffers.
• No persistence. Process restart wipes the cache; cold starts are painful.
• No coordination across processes. Each replica caches independently; warm caches do not share with each other.

Trade-offs (junior level)¶

Most of the trade-offs we will fix in the middle and senior files are about moving from the cheap side of these rows to the expensive side without paying the full cost.

Use Cases at the Junior Level¶

The cache you can build with this file is appropriate for:

• Single-process micro-services where requests are not bursty and the cache is small (< 100k entries).
• CLI tools that make repeated remote calls (e.g. a CI script that needs to look up the same package metadata many times).
• Tests that need a deterministic in-memory store of TTL'd state.
• Local development of a system that will eventually use Redis. Building your code against a Cache interface that this junior cache implements means you can swap to Redis later without changing call sites.
• Memoizing pure functions in tight loops.

It is not appropriate for:

• Public APIs receiving thousands of requests per second.
• Caches holding 10M+ entries.
• Multi-region or multi-replica deployments needing shared cache state.
• Anything where p99 latency is a hard SLO.

Clean-Code Considerations¶

Even a small cache benefits from disciplined naming and structure.

Name your type after its purpose, not its mechanism. SessionCache is better than TTLMap. The caller does not care whether it is implemented as a TTL'd map or a Redis client.

Hide internals. Make entry, data, mu, stop unexported. Expose only Get, Set, Delete, Close, and metrics.

Document the contract. Explicit godoc on each method:

// Get returns the value associated with key and true if the entry exists
// and has not yet expired. Otherwise it returns the zero value and false.
// Get is safe for concurrent use.
func (c *TTLCache) Get(key string) (string, bool) { ... }

Provide an interface. When the cache crosses a package boundary, define an interface for what the caller can do, not what the implementation can do:

type Cache interface {
    Get(key string) (string, bool)
    Set(key, value string)
    Delete(key string)
}

Now your tests can substitute a mock cache, and you can swap implementations without touching call sites.

Functional options for construction keep the constructor signature stable across future changes:

type Option func(*TTLCache)

func WithSweepInterval(d time.Duration) Option {
    return func(c *TTLCache) { c.sweepInterval = d }
}

func New(defaultTTL time.Duration, opts ...Option) *TTLCache {
    c := &TTLCache{defaultTTL: defaultTTL, sweepInterval: defaultTTL / 5}
    for _, o := range opts {
        o(c)
    }
    // ... start sweeper ...
    return c
}

Error Handling¶

A TTL cache has surprisingly few error conditions. The interesting ones:

• Calling methods after Close. Decision: panic (programmer error), no-op (silent), or return an error. Most popular: silent no-op for Set/Delete, miss for Get. Document it.
• Negative TTL passed to SetWithTTL. Decision: treat as "expire immediately" (most idiomatic), reject with panic, or default to zero. We recommend "expire immediately" — it is what time.Now().Add(-5*time.Second) produces naturally, and your Get's time.Now().After(expiresAt) check handles it cleanly.
• Nil cache. Calling Get on a nil *TTLCache panics with a nil-pointer dereference. Some libraries add an explicit check; most do not, on the principle that "do not call methods on nil" is a non-negotiable Go convention.

A common anti-pattern is logging from inside the cache. Resist it. The cache has no business knowing how the calling code wants errors reported; that is the caller's job. Return values, do not log.

Security Considerations¶

A cache is not usually thought of as a security-sensitive component, but it has its own attack surface.

Memory exhaustion via unique-key flooding. An attacker who can choose the cache key can pump millions of unique entries into the cache faster than the sweeper can clear them, leading to OOM. Defences:

• Cap the maximum cache size (LRU eviction — next subsection).
• Validate that keys come from a bounded universe (e.g. user IDs that exist).
• Rate-limit writes per source.

Leaking secrets through cache contents. If your cache holds session tokens, password hashes, or API keys, then a heap dump (e.g. from a crash) reveals them all in plaintext. Mitigations: encrypt at-rest if your threat model demands it, scrub entries on Delete, prefer short TTLs.

Side-channel: timing. If Get is faster on hits than on misses, an attacker can probe to discover whether certain keys exist. Usually not a meaningful concern for non-security data, but worth knowing.

Cache poisoning across tenants. If the cache is shared across customers and the key does not include the tenant ID, customer A may read customer B's cached data. Always include a tenant prefix in cache keys for multi-tenant systems.

These problems become much more interesting at scale, where attackers can deliberately try to construct collisions, evict useful entries, or amplify a single request into many. We touch on those in the professional file.

Performance Tips at the Junior Level¶

Most of the gains at this level come from "stop doing dumb things" rather than algorithmic cleverness.

1. Use RLock for reads, not Lock. The single change from Mutex to RWMutex typically doubles or triples read throughput.
2. Do not allocate per call. Returning a string value (not a pointer to a string) avoids garbage.
3. Do not log on every Get. A fmt.Printf inside Get will dominate every other cost in the function.
4. Batch insertions if possible. A single Set is cheap, but acquiring the lock 10,000 times in a tight loop is wasteful when you could acquire it once and insert 10,000 entries.
5. Skip the expired-check delete in Get. Let the sweeper handle it. Fewer write-lock acquisitions on the hot path.
6. Pre-size the map. If you know the cache will hold ~50,000 entries, make(map[string]entry, 50000) avoids repeated growth and rehashing.
7. Avoid interface{} if you can. With generics, you can hold concrete types and avoid the boxing cost.

You do not need to worry yet about:

• False sharing of cache lines.
• NUMA placement of memory.
• Sharded maps.
• runtime.LockOSThread.

Those become real only at very high throughput and are covered in the senior and professional files.

Best Practices¶

• Always store expiresAt as a time.Time, not as an int64, when the cache lives inside one process.
• Always have a Close method. Always plumb it into your application's shutdown.
• Always run tests with -race.
• Always include a hit/miss counter; without it you cannot tell whether the cache is doing its job.
• Always document whether Get returns a copy or a shared reference.
• Always reason about the worst case before changing the sweep interval; halving it doubles the lock-time fraction.

Edge Cases and Pitfalls¶

• Adding a key during sweep. The Go spec says new keys added during a range over a map may or may not be visible. In practice it does not matter because we add under the same lock as the sweep — they cannot happen simultaneously.
• TTL of exactly zero. Naive code may decide time.Now().After(time.Now()) is false (they are the same instant). With monotonic time this is correct; the entry is technically alive for the duration of the function call. Most callers should use TTL > 0.
• Very large values. Storing 10 MB strings in a cache is a recipe for memory pressure. Cap value size or store references.
• Keys with embedded nulls or non-printable bytes. Go maps handle them, but logs may render them oddly. Sanitise when logging.
• Sweeper falls behind. If sweep takes longer than sweepInterval, the ticker drops ticks; you do not get a pile-up of sweep calls. That is time.Ticker's documented behaviour.

Common Misconceptions¶

• "A TTL cache evicts entries exactly at their TTL." False — sweepers run on a schedule; entries may live longer.
• "Lazy eviction is wasteful." False — it is exactly right when memory pressure is not a problem and you want minimal goroutine overhead.
• "sync.Map is always faster than map + Mutex." False — sync.Map wins for very-low-mutation workloads but loses for balanced read/write.
• "I do not need to lock reads because they are atomic." False — Go maps are not safe for concurrent read+write; reads may crash even if no other reader is racing.
• "The race detector will catch all my races in CI." False — it only catches races that fire in the executed paths.

Migrating From an Unsafe Cache¶

You inherit a codebase with this:

var cache = map[string]string{}

func Get(k string) string { return cache[k] }
func Set(k, v string)     { cache[k] = v }

It compiles. It passes single-threaded tests. It crashes randomly in production with "fatal error: concurrent map writes." Your job: migrate it safely.

Three steps:

1. Add the mutex and lock every access: