Concurrency & Threading¶

The Aetherion engine uses a hybrid concurrency model, combining coarse-grained locking for physics with fine-grained task parallelism for the ecosystem.

Threading Model¶

Physics¶

Execution: Primarily runs on the main thread or a dedicated physics thread.
Locking: Uses physicsMutex to lock the entire engine during critical processing steps.

Ecosystem¶

Execution: Uses a Worker Thread Pool managed by WaterSimulationManager.
Task-Based: The world is split into tasks (GridBoxTask) processed concurrently by worker threads.

Locking Strategies¶

TerrainStorage Lock¶

The TerrainStorage (part of VoxelGrid) is a shared resource protected by a read-write lock.

Readers: Worker threads acquire read locks to analyze grid state.
Writers: The main thread or specific update tasks acquire write locks to apply changes (e.g., moving water).
Manual Control: The code explicitly calls lockTerrainGrid() and unlockTerrainGrid() in EcosystemEngine.cpp.

Concurrent Queues¶

tbb::concurrent_queue is used extensively for event handling between threads:

pendingEvaporateWater
pendingCreateWater
pendingWaterFall

Deadlock Risks¶

Warning

There is a high risk of deadlocks due to the interaction between manual locks and mutexes.

Scenario: If physicsMutex is held while trying to acquire TerrainStorage locks, and a worker thread holding a TerrainStorage lock tries to acquire physicsMutex (e.g., via an event), a deadlock will occur.
Mitigation: Ensure a strict lock ordering hierarchy. Always acquire physicsMutex before TerrainStorage locks if both are needed, or decouple the systems using event queues.