Implement thread-safe render queue decoupling event production from rendering #301

New issue

Closed

opened 2026-03-16 01:59:24 +00:00 by freemo · 0 comments

freemo commented

2026-03-16 01:59:24 +00:00

Owner

Metadata

Key	Value
Branch	`feature/m2-render-queue`
Commit Message	`feat: implement thread-safe render queue decoupling events from rendering`
Parent Epic	#298 — UI Event Subscription System

Background and Context

Game events can fire at any rate — a combat round might generate dozens of events in milliseconds. The render loop, however, runs at a fixed rate (20 FPS). A thread-safe queue is needed to decouple event production (game thread) from event consumption (render thread). Without this, either the game thread blocks waiting for rendering, or events are lost.

Expected Behavior

A RenderQueue (per player) acts as the bridge between event production and rendering. Game events processed through the EventProjection system produce RenderOps that are enqueued into the RenderQueue. The render thread drains the queue each frame and processes the accumulated RenderOps.

# Game thread (via EventProjection)
render_queue.enqueue(RenderOp.text_append(window: :main, text: "A goblin enters."))
render_queue.enqueue(RenderOp.bar_update(window: :status, bar: :hp, value: 85))

# Render thread (each frame)
ops = render_queue.drain
ops.each { |op| pipeline.process(op) }

The queue must be thread-safe (concurrent writes from game thread, reads from render thread) and efficient (no locking contention under normal load).

Acceptance Criteria

RenderQueue is instantiated per player.
#enqueue(render_op) is thread-safe for concurrent writes.
#drain returns all queued ops and clears the queue atomically.
#drain is safe to call from the render thread while game thread enqueues.
Queue handles burst scenarios (many events enqueued between frames).
Queue is bounded with configurable max size and overflow strategy (drop oldest).
Queue provides #size and #empty? for monitoring.

Subtasks

Code

Create RenderQueue class with thread-safe internal storage (Mutex + Array or Concurrent::Array).
Implement #enqueue(render_op) with thread safety.
Implement #drain returning all ops and clearing atomically.
Implement configurable max size with overflow strategy (drop oldest).
Implement #size and #empty? monitoring methods.
Integrate RenderQueue into player connection lifecycle (create on connect, destroy on disconnect).

Quality

Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/render_queue.feature covering single-threaded enqueue/drain, concurrent enqueue from multiple threads, drain atomicity, overflow with drop-oldest, empty drain, burst enqueue between drains, queue size monitoring.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for thread-safe render queue handling concurrent event production and consumption.
Tests (Profiling): Run bundle exec rake unit_profile and verify no performance regressions.
Quality: Verify coverage >=97% via bundle exec rake unit. If coverage is <97% then review the current unit test coverage report at build/tests/unit/coverage/ and use it to write new Cucumber based unit tests to improve coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun bundle exec rake unit to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
Quality: Run bundle exec rake (default task: unit tests with coverage) and bundle exec rake integration, fix any errors if needed ensuring both pass across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Key | Value | |-----|-------| | **Branch** | `feature/m2-render-queue` | | **Commit Message** | `feat: implement thread-safe render queue decoupling events from rendering` | | **Parent Epic** | #298 — UI Event Subscription System | ## Background and Context Game events can fire at any rate — a combat round might generate dozens of events in milliseconds. The render loop, however, runs at a fixed rate (20 FPS). A thread-safe queue is needed to decouple event production (game thread) from event consumption (render thread). Without this, either the game thread blocks waiting for rendering, or events are lost. ## Expected Behavior A `RenderQueue` (per player) acts as the bridge between event production and rendering. Game events processed through the EventProjection system produce `RenderOp`s that are enqueued into the `RenderQueue`. The render thread drains the queue each frame and processes the accumulated `RenderOp`s. ```ruby # Game thread (via EventProjection) render_queue.enqueue(RenderOp.text_append(window: :main, text: "A goblin enters.")) render_queue.enqueue(RenderOp.bar_update(window: :status, bar: :hp, value: 85)) # Render thread (each frame) ops = render_queue.drain ops.each { |op| pipeline.process(op) } ``` The queue must be thread-safe (concurrent writes from game thread, reads from render thread) and efficient (no locking contention under normal load). ## Acceptance Criteria - [ ] `RenderQueue` is instantiated per player. - [ ] `#enqueue(render_op)` is thread-safe for concurrent writes. - [ ] `#drain` returns all queued ops and clears the queue atomically. - [ ] `#drain` is safe to call from the render thread while game thread enqueues. - [ ] Queue handles burst scenarios (many events enqueued between frames). - [ ] Queue is bounded with configurable max size and overflow strategy (drop oldest). - [ ] Queue provides `#size` and `#empty?` for monitoring. ## Subtasks ### Code - [ ] Create `RenderQueue` class with thread-safe internal storage (Mutex + Array or Concurrent::Array). - [ ] Implement `#enqueue(render_op)` with thread safety. - [ ] Implement `#drain` returning all ops and clearing atomically. - [ ] Implement configurable max size with overflow strategy (drop oldest). - [ ] Implement `#size` and `#empty?` monitoring methods. - [ ] Integrate `RenderQueue` into player connection lifecycle (create on connect, destroy on disconnect). ### Quality - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/render_queue.feature` covering single-threaded enqueue/drain, concurrent enqueue from multiple threads, drain atomicity, overflow with drop-oldest, empty drain, burst enqueue between drains, queue size monitoring. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for thread-safe render queue handling concurrent event production and consumption. - [ ] Tests (Profiling): Run `bundle exec rake unit_profile` and verify no performance regressions. - [ ] Quality: Verify coverage >=97% via `bundle exec rake unit`. If coverage is <97% then review the current unit test coverage report at `build/tests/unit/coverage/` and use it to write new Cucumber based unit tests to improve coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `bundle exec rake unit` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Quality: Run `bundle exec rake` (default task: unit tests with coverage) and `bundle exec rake integration`, fix any errors if needed ensuring both pass across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.