Skip to content

utils: Implement Epoch-Based Reclamation (EBR) for Entity Management #10062

Open
pixelflinger wants to merge 2 commits into
mainfrom
ma/EntityManagerEBR
Open

utils: Implement Epoch-Based Reclamation (EBR) for Entity Management #10062
pixelflinger wants to merge 2 commits into
mainfrom
ma/EntityManagerEBR

Conversation

@pixelflinger

@pixelflinger pixelflinger commented May 27, 2026

Copy link
Copy Markdown
Collaborator

This major architectural update introduces an Epoch-Based Reclamation (EBR)
system to the EntityManager. It delays the recycling of destroyed Entity IDs
until all active readers and component managers have advanced past the epoch
in which the destruction occurred.

The primary motivation for EBR is to decouple the lifecycle of the 32-bit
Entity ID from the dense tracking structures. By guaranteeing that an entity's
physical index is never safely recycled while any subsystem is still processing
its destruction, component managers can safely transition to tracking entities
purely by their raw index, dropping the generation count from their internal
bitsets. This paves the way for drastically shrinking the memory footprint
of structures like PagedArenaBitset (e.g., from 16KB down to 256B) in future
updates.

Key changes:

  • Implement advanceEpoch(), registerWatermark(), and reclaimSafeEpochs()
    in EntityManager to orchestrate the global timeline.
  • Introduce catchupGarbage() in SingleInstanceComponentManager to
    periodically query the central timeline for missed garbage and mark
    entities logically dead.
  • Amortize the physical destruction of component data into a gc() phase,
    safely holding zombie components in dense arrays until they can be cleaned up.
  • Prevent use-after-free ID collisions by keeping destroyed Entity indices
    in a purgatory epoch until the global safe threshold clears them.
  • Introduce exhaustive concurrent stress tests to ensure thread-safety of
    the timeline and bitset pools.

@pixelflinger pixelflinger added the internal Issue/PR does not affect clients label May 27, 2026
@pixelflinger pixelflinger changed the title entity manager ebr wip: entity manager ebr May 27, 2026
@pixelflinger pixelflinger force-pushed the ma/EntityManagerEBR branch 3 times, most recently from dcdf2e5 to 63c0e78 Compare June 1, 2026 22:38
@pixelflinger pixelflinger changed the title wip: entity manager ebr utils: Implement Epoch-Based Reclamation (EBR) for Entity Management Jun 1, 2026
@pixelflinger pixelflinger requested review from poweifeng and z3moon June 1, 2026 22:39
@pixelflinger pixelflinger marked this pull request as ready for review June 1, 2026 22:40
@pixelflinger pixelflinger force-pushed the ma/EntityManagerEBR branch from 63c0e78 to 2404250 Compare June 4, 2026 15:18
Comment thread libs/utils/include/utils/PagedArenaBitset.h Outdated
Comment thread libs/utils/src/EntityManagerImpl.h Outdated
@pixelflinger pixelflinger force-pushed the ma/EntityManagerEBR branch from 2404250 to c6bf38c Compare June 5, 2026 22:10
This allows to iterated a bitset while also clearing the visited bits.
@pixelflinger pixelflinger force-pushed the ma/EntityManagerEBR branch from c6bf38c to 87d07a0 Compare June 8, 2026 15:15
This major architectural update introduces an Epoch-Based Reclamation (EBR)
system to the EntityManager. It delays the recycling of destroyed Entity IDs
until all active readers and component managers have advanced past the epoch
in which the destruction occurred.

The primary motivation for EBR is to decouple the lifecycle of the 32-bit
Entity ID from the dense tracking structures. By guaranteeing that an entity's
physical index is never safely recycled while any subsystem is still processing
its destruction, component managers can safely transition to tracking entities
purely by their raw index, dropping the generation count from their internal
bitsets. This paves the way for drastically shrinking the memory footprint
of structures like PagedArenaBitset (e.g., from 16KB down to 256B) in future
updates.

Key changes:
- Implement `advanceEpoch()`, `registerWatermark()`, and `reclaimSafeEpochs()`
  in EntityManager to orchestrate the global timeline.
- Introduce `catchupGarbage()` in SingleInstanceComponentManager to
  periodically query the central timeline for missed garbage and mark
  entities logically dead.
- Amortize the physical destruction of component data into a `gc()` phase,
  safely holding zombie components in dense arrays until they can be cleaned up.
- Prevent use-after-free ID collisions by keeping destroyed Entity indices
  in a purgatory epoch until the global safe threshold clears them.
- Introduce exhaustive concurrent stress tests to ensure thread-safety of
  the timeline and bitset pools.
@pixelflinger pixelflinger force-pushed the ma/EntityManagerEBR branch from 87d07a0 to 7c9ba80 Compare June 8, 2026 19:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

internal Issue/PR does not affect clients

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants