looper/evaluation.md

Code Evaluation

Summary Table

Category	Rating	Remarks
Mocked / Left Undone	✅ Minor	CMD_STOP is only reachable via the FIFO pipe ("stop"). The MIDI handler never sends it. This is an unused path, not a bug. The FIFO pipe is still untested in the integration suite – all tests use MIDI. No test for "stop" via FIFO. Everything else is implemented and matches the test suite.
Potential Segfaults	✅ Good	All jack_port_get_buffer() calls are guarded against NULL. Array bounds respected (fixed‑size loops). SPSC queues use modulo arithmetic, no overrun possible. No dynamic memory in RT path.
Memory Safety	✅ OK	No leaks, no use‑after‑free. All buffers static. Deferred port unregistration waits for at least one RT cycle after active=0 – safe. The FIFO reader thread uses stack memory for line reading.
Thread Safety / Race	✅ Good	SPSC queues have correct acquire/release ordering. Multi‑producer issue on main‑loop commands has been fixed by giving each producer its own queue (cmd_queue_main_midi for MIDI, cmd_queue_main_fifo for FIFO). The RT callback only writes to cmd_queue_main_midi; the FIFO thread only writes to cmd_queue_main_fifo. Both are consumed solely by the main loop, restoring SPSC safety. The deferred unregistration race is now fixed via global_rt_cycles counter – the main loop ensures the RT thread has completed a cycle after active=0 before calling jack_port_unregister(). prev_state is a plain int but accessed only from the RT callback (single thread). All other shared state (state, active, control_key_active, bind_channel) uses atomics.
Performance	✅ Good	No syscalls, locks, or dynamic allocations in the RT callback. Two queue drains (one for RT commands, one for main‑loop commands) add negligible overhead. O(1) queue operations. Linear audio processing.
Architectural Soundness	✅ Good	Clean separation: each input source has its own SPSC queue for non‑RT commands; RT callback drains its own queue; main loop drains both auxiliary queues. The command queue approach is now fully uniform (no atomic flags remaining for add/remove). The FIFO pipe works in parallel. The code is easily extensible to new input sources.

Detailed Remarks

1. Mocked / Left Undone

• CMD_STOP is only reachable via the FIFO pipe ("stop"). The MIDI handler never sends it. This is not a bug, just an unused feature path.
• The FIFO pipe is completely untested in the main integration suite. All existing tests use MIDI notes. Adding a FIFO‑based test would increase coverage.
• No other functionality is missing.

2. Potential Segfaults

• Every jack_port_get_buffer() call is followed by a null check (if (!out) continue;).
• Array accesses are bounded by MAX_CHANNELS and QUEUE_CAPACITY.
• No use of malloc or variable‑length arrays in the real‑time callback.
• The only unguarded jack_port_get_buffer() is in midi_handle_events where the caller already checks midi_ctrl_buf against NULL. Safe.

3. Memory Safety

• All loop_buffer arrays and command queue buffers are static globals. No heap allocation in RT context.
• Port unregistration is deferred until after the RT thread has surely passed the active=0 check (via global_rt_cycles). No use‑after‑unregister possible.
• The FIFO reader thread uses a stack‑allocated line buffer – safe.
• No memory leaks are present.

4. Thread Safety / Race Conditions

• RT‑safe commands queue (cmd_queue) – single writer (MIDI handler, called from RT callback) and single reader (the same callback, immediately after writing). Correct.
• Add/remove command queues – two separate SPSC queues:
  • cmd_queue_main_midi: written only by the RT callback (via midi_handle_events).
  • cmd_queue_main_fifo: written only by the FIFO reader thread (non‑RT). Both are read only by the main loop (single consumer). No concurrent writes to the same queue.
• global_rt_cycles is incremented with memory_order_release at the end of every process callback. The main loop reads it with implicit acquire. This ensures visibility of the store to active and prevents unregistering ports while the RT thread may still be using them.
• channel_add() and channel_remove() are called only from the main loop, never from the RT callback. The RT callback reads active, state, audio_in, audio_out (all atomic). Safe.
• prev_state is a plain int but written and read only from the RT callback – no data race.

5. Performance

• The RT callback performs:
  1. MIDI event processing (may push to cmd_queue and cmd_queue_main_midi).
  2. Drain cmd_queue (O(1) per command, usually 0–2 commands).
  3. Per‑channel audio processing (linear buffer copy or playback).
  4. MIDI clock event handling (rare).
  5. Increment global_rt_cycles (atomic store).
• No syscalls, no locks, no printf in the RT path.
• The main loop runs at 50 ms intervals; draining two queues is negligible.

6. Architectural Soundness

• The design cleanly separates RT‑safe command handling (immediate in the process callback) from non‑RT operations (deferred to the main loop).
• Each input source (MIDI, FIFO) has its own dedicated SPSC queue for commands that must be processed outside the RT thread. This avoids the multi‑producer race that existed before.
• All commands are represented by a uniform command_t structure with a typed enum. No ad‑hoc atomic flags remain.
• The FIFO pipe reader runs in a detached thread – simple and non‑blocking.
• The code is easy to extend: adding a new input source (e.g., network socket) would involve creating a new SPSC queue and another drain loop.

Overall Verdict

The code is safe, race‑free, and architecturally sound. It meets all real‑time constraints and correctly implements the looper’s state machine with unified command handling from MIDI and a FIFO pipe.

Minor remaining items:

• The FIFO pipe is untested in the integration suite.
• CMD_STOP is not triggered from MIDI (only from FIFO).
• The existing evaluation.md is outdated and should be replaced with this evaluation.