skip to content

Why do game engines refer to entities and resources through handles with generation counts rather than raw pointers, and how is a stale handle caught?

level: middleimportance: should knowfreq 50%

answer

  1. objects die while others still refer
  2. index into a table of slots
  3. a counter bumped on every free
  4. compare before you dereference
  5. lets the owner move objects

basics

~20 s

A handle is a slot index plus a generation number. Freeing an object bumps its slot's generation, so resolving an old handle finds a mismatch and returns nothing instead of touching a dead object or the new one that reused the slot.

solid answer

~50 s

Game objects die constantly while other systems still refer to them: an enemy is killed while a turret targets it, a sound is unloaded while an emitter points at it. A raw pointer to a freed object dangles, and once the memory is reused it silently points at a different object. A **handle** stores an index into a table of slots plus the **generation** that slot had when the object was created. Destroying the object increments the slot's generation and puts the slot on a free list. Resolving a handle checks that the index is in range and the generations match, and returns null otherwise, so the turret learns its target is gone. Because everyone goes through the table, the owner can also move objects, for example to compact a pool, and update only the table. The costs are an extra indirection per access and generation wrap-around after enough reuses of one slot.

code

pseudocode · 30 lines
pseudocode
Handle = { index, generation }      // e.g. 20-bit index, 12-bit generation

HandleTable
  slots: array of { object, generation, nextFree }
  freeHead: int

  create(obj):
    if freeHead == NONE:
      return INVALID_HANDLE
    i = freeHead
    freeHead = slots[i].nextFree
    slots[i].object = obj
    return Handle(i, slots[i].generation)

  resolve(h):
    if h.index >= length(slots):
      return NONE
    s = slots[h.index]
    if s.generation != h.generation:
      return NONE                       // destroyed, maybe reused
    return s.object

  destroy(h):
    if resolve(h) == NONE:
      return                            // already dead: double destroy ignored
    s = slots[h.index]
    s.object = NONE
    s.generation = (s.generation + 1) mod 4096
    s.nextFree = freeHead
    freeHead = h.index

go deeper

for a junior

Recall that a handle is an index plus a generation number and that a mismatch means the object it named is gone.

for a middle

Explain create, destroy and resolve, why destroy bumps the generation, and how that catches both stale handles and double destroys.

for a senior

Discuss relocation through the table, the cost of indirection in hot loops, not caching resolved pointers across frames, and choosing generation width against churn.

for a principal

Argue where an engine standardises on handles versus raw pointers or counted references, and how that rule is enforced across teams' code.

## The dangling-pointer problem in a game In a running game, objects are destroyed far more often than in most programs: enemies die, projectiles hit, pickups are collected, streamed-out resources are unloaded. Other systems often still refer to them. A turret's AI holds its current target, a UI marker follows a quest item, a material refers to a texture. If those references are **raw pointers**, destroying the object leaves them **dangling**, and the bug is worse than a crash: once the slot or memory is reused, the pointer is valid-looking and points at a **different** object. The turret now tracks a random new enemy, and nothing reports it. A **generational handle** turns that silent aliasing into a check that fails cleanly. ## Anatomy of a handle A handle is a small integer split into two fields: | Field | Meaning | Example width (32-bit handle) | |---|---|---| | index | which slot in the owner's table | 20 bits, so 2^20 = 1,048,576 slots | | generation | the slot's reuse count, modulo its range, when the handle was made | 12 bits, so 2^12 = 4,096 values | The table keeps, for each slot, the object (or a pointer to it), the slot's **current generation**, and a free-list link. The widths are a design choice; the example's split is a scenario's, not a standard. ## Create, destroy, resolve 1. **Create**: pop a free slot, store the object, and return a handle holding the slot's index and its current generation. 2. **Destroy**: increment the slot's generation (modulo its range), clear the object and push the slot onto the free list. 3. **Resolve**: check the index is in range, then compare the handle's generation with the slot's. Equal means the object is the one the handle was made for; different means it was destroyed, possibly replaced, and the lookup returns null. A handle is resolved at the point of use, every time, and the resolved pointer is not stored. Resolving costs one bounds check, one compare and one indirection. ## What handles buy beyond safety - **Relocation.** Because every access goes through the table, the owner can move objects, for example to keep a pool dense for iteration or to compact memory, and fix up only the table entry. - **Compactness.** A 32-bit handle is half a 64-bit pointer, which matters in dense arrays of references iterated every frame. - **Clear ownership.** One system owns the table and decides when objects die. Holding a handle never keeps an object alive, which matches gameplay: a killed enemy is dead even if a turret still remembers it. - **Cheap validation.** Double-destroy is caught by the same compare: the second destroy resolves to nothing and returns. ## Costs and limits - **Indirection.** Every access is a table lookup that may miss the cache. Hot inner loops resolve once and work on the result within that loop. - **Wrap-around.** With a 12-bit generation, after 4,096 reuses of the same slot the counter returns to its old value and a very old stale handle would match again. Wider generations push this out; some designs retire a slot whose generation is about to wrap. - **Holding the resolved pointer.** Storing the pointer a handle resolved to brings the dangling problem back. The rule is to resolve again after any point where objects can be destroyed, such as the next frame. - **Not a persistent identity.** A slot index is meaningful only in this run's table, so save games or editor references need a separate stable identifier. ## Handles compared with other reference schemes | Scheme | Keeps the object alive? | Detects a dead object? | Lets the owner move it? | |---|---|---|---| | Raw pointer | no | no | no | | Reference counting | yes | not needed while counted | no | | Generational handle | no | yes, by generation compare | yes | Reference counting answers a different question (when may this be freed?), and in a game the answer is usually "when gameplay says it died", which is the handle model.

  • Why not use reference counting so the turret's target simply stays alive?
    Keeping a dead enemy alive because a turret remembers it is the wrong gameplay semantics, and counts make lifetime depend on every holder releasing correctly, which leaks easily. A handle leaves the decision with the owner: the enemy dies when gameplay kills it, and holders find out on their next resolve.
  • When does generation wrap-around become a real risk, and what do you do about it?
    When a slot is reused many times while some system holds a very old handle, as with high-churn pools such as projectiles. With 12 bits, 4,096 reuses of one slot bring the generation back around. Widen the generation, spread reuse across slots, or retire a slot whose generation is about to wrap.

  • A handle is just an array index, so reuse is harmless
  • Holding a handle keeps the referenced object alive
  • Resolve a handle once and cache the pointer forever
  • The indirection cost alone makes handles a bad trade
  • Generation counters can never wrap around in practice