fase 4+5: fibers cooperatius substitueixen el game thread, sense mutex ni cv
This commit is contained in:
56
CLAUDE.md
56
CLAUDE.md
@@ -131,7 +131,7 @@ Follows the pattern from `jaildoctors_dilemma`, persists to YAML:
|
||||
| F8 | Cycle shader presets |
|
||||
| F9 | Toggle stretch filter (nearest ↔ linear) |
|
||||
| F10 | Cycle render info (off → top → bottom → off) |
|
||||
| F11 | Toggle pause (blocks game thread at publishFrame + `JA_PauseMusic`/`JA_ResumeMusic`) |
|
||||
| F11 | Toggle pause (Director stops resuming the game fiber + `JA_PauseMusic`/`JA_ResumeMusic`) |
|
||||
| F12 | Toggle floating options menu |
|
||||
| ESC | Double-press to quit (with overlay notification) / close menu if open |
|
||||
| Backspace | Go up one menu level / close menu if at root |
|
||||
@@ -139,33 +139,45 @@ Follows the pattern from `jaildoctors_dilemma`, persists to YAML:
|
||||
|
||||
All key bindings are configurable via `Options::keys_gui` and stored in `config.yaml` (section `controls:` with SDL scancode names). Game movement keys (`Options::keys_game.up/down/left/right`) can be remapped via the CONTROLS submenu — the `KeyRemap` module mirrors custom physical keys to virtual standard scancodes so hardcoded game code keeps working.
|
||||
|
||||
### Threading Model (Emulator Architecture — transitional)
|
||||
|
||||
> ⚠️ This architecture is **transitional**. It will be dismantled in Phase 5 of the modernization plan (the game thread + `publishFrame` mutex/cv disappear) and replaced by a single-threaded `SDL_AppIterate` loop in Phase 7. Document changes here when that happens.
|
||||
### Execution Model (Single-threaded Fibers)
|
||||
|
||||
Since Phase 4+5, the old game thread + `publishFrame` mutex/cv has been **removed**. The game code (`ModuleGame`, `ModuleSequence`, all their `Go()` methods with internal `while` loops) runs inside a **cooperative fiber** (see [fiber.hpp](source/core/system/fiber.hpp) / [fiber.cpp](source/core/system/fiber.cpp)). The whole process is single-threaded.
|
||||
|
||||
```
|
||||
Main thread (Director) Game thread (ModuleGame/Sequence::Go())
|
||||
──────────────────── ────────────────────────────────────
|
||||
loop at ~60 FPS { loop {
|
||||
SDL_PollEvent() ... game logic ...
|
||||
GlobalInputs, Mouse JD8_Flip():
|
||||
if new_frame_available: palette→ARGB in pixel_data
|
||||
copy to game_frame publishFrame(pixel_data) ⏸
|
||||
signal → ────────────────────→ (blocks until Director consumes)
|
||||
copy game_frame → present_buffer ←──── signal_consumed
|
||||
Overlay::render(present_buffer) continue game loop
|
||||
Screen::present(present_buffer) }
|
||||
Main thread (only thread)
|
||||
─────────────────────────
|
||||
Director::run() loop {
|
||||
SDL_PollEvent()
|
||||
GlobalInputs, Mouse, KeyRemap
|
||||
JA_Update() ← audio pump
|
||||
if !paused:
|
||||
GameFiber::resume() ← hands control to game code
|
||||
↓ (runs until next JD8_Flip)
|
||||
... game code runs ...
|
||||
JD8_Flip():
|
||||
palette → ARGB → pixel_data
|
||||
GameFiber::yield() ← returns control to Director
|
||||
↓
|
||||
copy JD8_GetFramebuffer() → game_frame
|
||||
memcpy game_frame → presentation_buffer
|
||||
Overlay::render(presentation_buffer)
|
||||
Screen::present(presentation_buffer)
|
||||
SDL_Delay to hit 60fps
|
||||
}
|
||||
```
|
||||
|
||||
**Fiber backend** ([fiber.cpp](source/core/system/fiber.cpp)):
|
||||
- **Linux / macOS**: `ucontext_t` + `makecontext`/`swapcontext` (deprecated in POSIX.1-2008 but still functional in glibc and macOS libc; warning silenced with `#pragma`).
|
||||
- **Windows**: `ConvertThreadToFiber` / `CreateFiber` / `SwitchToFiber` (native Fibers API).
|
||||
- **Emscripten**: not yet. Phase 7 will add an `emscripten_fiber_*` or Asyncify backend.
|
||||
|
||||
**Key points:**
|
||||
- Director is NON-BLOCKING: if no new frame, re-presents the last one with fresh overlay
|
||||
- Double buffer: `game_frame` (untouched copy from game) + `presentation_buffer` (regenerated with overlay each frame)
|
||||
- Game thread pauses at `JD8_Flip()` waiting for Director — natural sync point
|
||||
- SDL events processed ONLY on main thread (SDL requirement)
|
||||
- `JI_Update()` no longer polls events — reads Director's state
|
||||
- Single-threaded: zero `std::thread`, zero `std::mutex`, zero `std::condition_variable`.
|
||||
- `JD8_Flip()` is the natural sync point: it calls `GameFiber::yield()` instead of the old blocking `publishFrame`.
|
||||
- Pause (F11) works by Director skipping `resume()`: the fiber stays frozen at its last yield, and Director keeps repainting the last frame with fresh overlay.
|
||||
- Double buffer still exists (`game_frame` + `presentation_buffer`) because Director can present multiple frames per game frame during pause or slow sections. Eliminating it is marginal work and the extra 256 KB copy is cheap at 320×200.
|
||||
- The state machine alternating `ModuleSequence` (state=1) and `ModuleGame` (state=0) now lives in `gameFiberEntry()` inside an anonymous namespace in [director.cpp](source/core/system/director.cpp), called once as the fiber entry point.
|
||||
- SDL events still processed only on the main thread (which is now the only thread anyway).
|
||||
|
||||
### Rendering Pipeline (inside Screen::present)
|
||||
|
||||
@@ -217,7 +229,7 @@ JD8_Flip produces ABGR byte order: `0xFF000000 + R + (G<<8) + (B<<16)`. SDL text
|
||||
4. **Raw `malloc`/`free` in gameplay structs**: `Sprite`/`Entitat` use `malloc` for `Frame[]` and `Animacio[]`; `jfile.cpp` uses a global `scratch[255]` buffer (UB under concurrent calls); `jail_audio.cpp` mixes `new`/`malloc`/`SDL_malloc`. Scheduled for Phase 1 (RAII pass).
|
||||
5. **Blocking loops in cinematics and fades**: `ModuleSequence::doIntro()` has 15+ `while(!JG_ShouldUpdate())` spin-waits; `JD8_FadeOut`/`JD8_FadeToPal` run 32 internal iterations calling `JD8_Flip`. Incompatible with `SDL_AppIterate`. Scheduled for Phase 2 (state-machine refactor).
|
||||
6. ~~**`SDL_AddTimer` in audio**~~: Fixed in Phase 3. `jail_audio` is now a header-only `inline` module (single `.cpp` stub only hosts the `stb_vorbis` implementation to avoid multiple definitions). Music uses true streaming via `stb_vorbis_open_memory` + `JA_PumpMusic` with a 0.5s low-water-mark instead of decoding the whole OGG into RAM. Mixing/fade update runs manually via `JA_Update()` called once per frame from `Director::run()`. Ported from the `jaildoctors_dilemma` codebase.
|
||||
7. **Game thread + `publishFrame` mutex/cv**: the emulator-style architecture is only tenable while native. Incompatible with `SDL_AppIterate`. Scheduled for Phase 5 (single-threaded state machine).
|
||||
7. ~~**Game thread + `publishFrame` mutex/cv**~~: Fixed in Phase 4+5. Replaced by a cooperative `GameFiber` (ucontext on POSIX, Fibers API on Windows). `JD8_Flip()` calls `GameFiber::yield()`, Director calls `GameFiber::resume()` once per frame. Zero threads, zero mutexes. Emscripten fiber backend still pending for Phase 7.
|
||||
|
||||
### Pending / Ideas for Later
|
||||
|
||||
@@ -249,4 +261,4 @@ Director loop uses `FRAME_MS_VSYNC = 16` (60 FPS) or `FRAME_MS_NO_VSYNC = 4` (~2
|
||||
|
||||
Init order: `file_setconfigfolder` → `Options::load` → `Locale::load("locale/ca.yaml")` → `Options::loadPostFX/CrtPi` → `JG_Init` → `Screen::init` → `JD8_Init` → `JA_Init` → `Options::applyAudio()` → `Overlay::init` → `Menu::init` → `Director::init` (also calls `Gamepad::init()`) → `Director::run()` (blocks until quit). Shutdown: `Options::save` → `Director::destroy` → `Menu::destroy` → `Overlay::destroy` → `JA_Quit` → `JD8_Quit` → `Screen::destroy` → `JG_Finalize`.
|
||||
|
||||
The state machine (alternating `ModuleSequence` state=1 and `ModuleGame` state=0) now lives inside `Director::gameThreadFunc()`, running on the game thread.
|
||||
The state machine (alternating `ModuleSequence` state=1 and `ModuleGame` state=0) lives inside `gameFiberEntry()` in an anonymous namespace in [director.cpp](source/core/system/director.cpp), invoked as the entry of the cooperative fiber (single-threaded).
|
||||
|
||||
Reference in New Issue
Block a user