Scene 05a

TTL and cleanup — lazy, active, and the freer thread

TTL expiration runs on two independent paths — passive on access plus a 10Hz active sampler that pulls 20 random TTL'd keys per tick and resamples while >25% are expired — and the cleanup itself stalls the single loop on a big DEL unless lazyfree-* (or UNLINK) hands the free to the background thread.

Previously

Eviction is the memory-pressure path. TTL is the clock path — keys leave because their time is up, not because Redis ran out of room. Same lazyfree lane, different trigger.

Scene 05a

TTL and cleanup — lazy, active, and the freer thread

Watch
Try it
Predict
Capture

What to watch for

The 10Hz active-expire ticker pulses across the top. Each pulse samples a small random subset of the TTL'd cells (production Redis: 20 against millions of keys; this demo: 4 against 12 — see the pseudocode for the production constant). Expired cells in the sample drain to the right-side counter; expired cells the sampler missed pile up on the EXPIRED-BUT-RESIDENT lag gauge. A passive GET on an expired key deletes it inline. Replicas don't actively expire — they wait for the master's DEL.

Implementation

Highlighted lines are the ones running in the diagram right now.

activeExpireCycle

10Hz tick: sample 20 TTL'd keys, resample if >25% expired

1def activeExpireCycle():       # runs every 100ms
2    for round in range(max_rounds):
3        sample = random_sample(db.expires, n=20)
4        expired = [k for k in sample
5                   if k.expire_at <= now()]
6        for k in expired:
7            deleteOrLazyfree(k)   # lazyfree-lazy-expire
8        ratio = len(expired) / len(sample)
9        if ratio <= 0.25: return  # under threshold, rest
10        if cpu_used() > active_expire_budget: return
11        # else: resample inside the same 100ms tick

lookupKey (passive expire)

every GET checks the TTL; expired ⇒ delete inline, return nil

1def lookupKey(db, key):
2    entry = db.get(key)
3    if entry is None: return None
4    if entry.has_ttl and entry.expire_at <= now():
5        deleteOrLazyfree(entry)   # passive path
6        return None               # GET returns nil
7    return entry.value

deleteOrLazyfree

DEL stalls the loop; UNLINK / lazyfree-* hands off to bg thread

1def deleteOrLazyfree(entry):
2    cost = estimate_free_cost(entry)  # ~elements to walk
3    offload = (cost > LAZYFREE_THRESHOLD
4               or lazyfree_for(entry.callsite))
5    if offload:
6        unlink_from_keyspace(entry)   # O(1) on the loop
7        background_freer_queue.push(entry)
8    else:
9        walk_and_free(entry)          # WHOLE struct, on the loop

Sources

Where this sits in Build Redis

Scene 05a of 10, in the Memory act — Persistence, eviction, TTL — what makes RAM disappear.. Passive + 10Hz active sampler expire keys; DEL of a big value freezes the loop unless `lazyfree-*`/UNLINK offloads to the background freer thread. Cache stampede + jitter / SET NX rebuilder lock.

Up next. Replication — one node now has every cleanup mechanic in place. But one node is still a single point of failure. Keeping a copy on another node is the first answer.

All 10 scenes in Build Redis · Every curriculum

Designs that use this

Built with Arqly

Every scene in Build Redis builds on the one before it.All 10 Build Redis scenes