StillHammer
69f5a1cc6c
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
94 lines
3.0 KiB
Markdown
94 lines
3.0 KiB
Markdown
# GroveEngine - Claude Code Context
|
|
|
|
## Project Overview
|
|
GroveEngine is a C++17 hot-reload module system for game engines. It supports dynamic loading/unloading of modules (.so) with state preservation during hot-reload.
|
|
|
|
## Build & Test
|
|
```bash
|
|
# Build
|
|
cmake -B build && cmake --build build -j4
|
|
|
|
# Run all tests (23 tests)
|
|
cd build && ctest --output-on-failure
|
|
|
|
# Build with ThreadSanitizer
|
|
cmake -DGROVE_ENABLE_TSAN=ON -B build-tsan
|
|
cmake --build build-tsan -j4
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Key Components
|
|
- **ModuleLoader**: Handles dlopen/dlclose of .so modules with hot-reload support
|
|
- **SequentialModuleSystem**: Single-threaded module execution for testing
|
|
- **IntraIOManager**: Inter-module communication with pub/sub routing
|
|
- **TopicTree**: O(k) topic matching with wildcard support
|
|
|
|
### Thread Safety Patterns
|
|
See `docs/coding_guidelines.md` for detailed synchronization guidelines.
|
|
|
|
**DO:**
|
|
```cpp
|
|
// Multiple mutexes - use scoped_lock (deadlock-free)
|
|
std::scoped_lock lock(mutex1, mutex2);
|
|
|
|
// Read-heavy data - use shared_mutex
|
|
std::shared_lock readLock(sharedMutex); // concurrent reads
|
|
std::unique_lock writeLock(sharedMutex); // exclusive write
|
|
```
|
|
|
|
**DON'T:**
|
|
```cpp
|
|
// NEVER nest lock_guard - causes deadlock
|
|
std::lock_guard lock1(mutex1);
|
|
std::lock_guard lock2(mutex2); // DEADLOCK RISK
|
|
```
|
|
|
|
### ModuleLoader Usage
|
|
- Each `ModuleLoader` instance manages ONE module lifecycle
|
|
- Don't reuse loader for multiple independent modules (causes SEGFAULT)
|
|
- `reload()` safely handles state extraction and library reload
|
|
- `load(path, name, isReload=true)` for hot-reload with cache bypass
|
|
|
|
## Known Issues
|
|
- **TankModule.h linter bug**: A linter sometimes merges lines 35-36. If build fails with "logger not declared", check this file.
|
|
|
|
## Test Categories
|
|
| Test # | Name | Duration | Description |
|
|
|--------|------|----------|-------------|
|
|
| 1-10 | scenario_* | ~0.01s | Basic scenarios |
|
|
| 11 | ProductionHotReload | ~12s | Full hot-reload cycle |
|
|
| 12 | ChaosMonkey | ~41s | Stress testing |
|
|
| 13 | StressTest | ~180s | Heavy load |
|
|
| 15 | MemoryLeakHunter | ~135s | 200 reload cycles |
|
|
| 19 | CrossSystemIntegration | ~4s | Multi-system test |
|
|
|
|
## BgfxRenderer Module
|
|
2D rendering module using bgfx. Located in `modules/BgfxRenderer/`.
|
|
|
|
### Architecture
|
|
- **RHI Layer**: Abstracts bgfx calls (`RHIDevice.h`, `BgfxDevice.cpp`)
|
|
- **RenderGraph**: Topological sort with Kahn's algorithm for pass ordering
|
|
- **CommandBuffer**: Records commands, executed by device at frame end
|
|
- **IIO Topics**: `render:sprite`, `render:camera`, `render:debug/*`
|
|
|
|
### Build
|
|
```bash
|
|
cmake -DGROVE_BUILD_BGFX_RENDERER=ON -B build
|
|
cmake --build build -j4
|
|
```
|
|
|
|
### Documentation
|
|
- `modules/BgfxRenderer/README.md` - Module overview
|
|
- `docs/PLAN_BGFX_RENDERER.md` - Implementation plan
|
|
|
|
## Debugging Tools
|
|
```bash
|
|
# ThreadSanitizer (detects data races, deadlocks)
|
|
cmake -DGROVE_ENABLE_TSAN=ON -B build-tsan
|
|
|
|
# Helgrind (alternative deadlock detector)
|
|
cmake -DGROVE_ENABLE_HELGRIND=ON -B build
|
|
make helgrind
|
|
```
|