Module Lifecycle State Machine
GroveEngine • Circular Flow • Hot-Reload Cycle
UNLOADED
Initial state
No .so/.dll loaded
LOADED
Library loaded
createModule()
CONFIGURED
Config set
IIO connected
RUNNING
Active execution
process() loop
60 FPS
ERROR
Exception caught
Recovery possible
SHUTDOWN
Cleanup complete
Module destroyed
HOT-RELOAD
Extract state (0.1ms)
Unload/Load (0.2ms)
Restore state (0.1ms)
load()
setConfig()
process()
process()
Exception
Fatal
unload()
recover()
shutdown()
reload()
0.4ms
restored
Hot-Reload Cycle (0.4ms)
1. Extract State:
auto state = module->getState();
0.1ms
2. Unload Library:
dlclose(handle);
0.05ms
3. Load New Library:
handle = dlopen(path, RTLD_NOW);
0.15ms
4. Restore State:
module->setState(state);
0.1ms
State Preservation (100%)
What gets preserved:
• Player position, velocity, health
• Enemy AI states, pathfinding data
• UI widget states, text inputs
• Timers, counters, game state
• Any serializable module data
Configuration Phase
setConfiguration(config, io, scheduler):
• config: IDataNode (JSON/XML)
• io: IIO for pub/sub messaging
• scheduler: ITaskScheduler
IModule Interface
Required methods:
• process(deltaTime) - Main loop (60 FPS)
• getState() - Serialize to IDataNode
• setState(state) - Deserialize
• setConfiguration() - Init config
• shutdown() - Clean cleanup
Performance Metrics
Cold start (UNLOADED→RUNNING):
~51ms
Hot-reload cycle:
0.4ms avg
(0.055ms best)
State Legend
Unloaded - Initial/Final
Loaded - Library in memory
Configured - Ready to start
Running - Active execution
Hot-Reload - 0.4ms transition
Typical Development Flow
1. Load module once (UNLOADED→RUNNING)
2. Edit code in VSCode/IDE
3. Build with cmake (300ms)
4. Hot-reload (0.4ms, 60+ times/hour)
Error Handling
Exception in process() → ERROR state
Recovery possible → back to RUNNING
Fatal error → SHUTDOWN
Module logs errors via spdlog
Key Benefits
✓ Sub-millisecond reload (0.4ms avg)
✓ 100% state preservation
✓ Game keeps running (no restart)
✓ Zero context switching
✓ Instant feedback loop
✓ Perfect for rapid prototyping
Implementation Notes
• Each ModuleLoader manages ONE module
• Don't reuse loaders (causes SEGFAULT)
GroveEngine © 2025 • Hot-Reload System • Zero-downtime Development