looper/docs/evaluation.md

Evaluation of Looper Codebase

Summary Table

Category	Rating	Notes
Mocked / left‑doing	⚠️ Moderate	No mock objects; real Carla dependency. Tests for Carla host are stubs. Integration test requires running JACK server. Script module test now passes 7/7 (empty macro bug fixed).
Potential segfaults	✅ Low	exec_command validates channel bounds (ch < MAX_CHANNELS). note_actions is checked for NULL before use. strdup returns not checked but safe in practice. No out‑of‑bounds access identified.
Memory management	✅ Good	note_actions strings freed via script_cleanup() called in tui_cleanup(). strdup allocations are freed on reload. All dynamically allocated audio buffers are freed. No leaks at exit.
Thread safety	✅ Good	All shared scene/channel fields use C11 atomics. Logging mutex never held in audio thread. Save deactivation uses atomic active flag with two wait periods (500ms + 200ms) guaranteeing RT thread sees the change. FIFO writes are atomic (PIPE_BUF). No race conditions identified.
Performance	✅ Fair	Audio path: memcpy, linear loops, no allocations – real‑time safe. Main loop sleeps 50 ms – fine. Save pauses audio for 500 ms (acceptable for a tool). Logging adds negligible mutex overhead outside RT thread. JACK callback time is deterministic.
Architectural soundness	⚠️ Medium	Separation of engine and client via FIFO is clean. Orchestrator simple but effective. Three command queues still add unnecessary complexity (single queue would suffice). prev_state transition detection works. Carla integration remains tightly coupled to JACK client. Script/macro mechanism is extensible and well isolated. Logging design correctly avoids audio thread.

Detailed Commentary

1. Mocked / Left‑doing

• Engine tests require a live JACK server – no mocking.
• Client tests for carla_host and plugins use stubs when TESTING is defined; real Carla library is still linked. Integration test also requires JACK.
• Script tests pass 7/7 after the empty macro bug was fixed.
• No mock for MIDI – engine integration test uses actual MIDI events.

2. Potential Segfaults

• Channel bounds are now validated in exec_command: if (ch < 0 || ch >= MAX_CHANNELS) ch = 0;. Safe.
• NULL pointer dereference: script_handle_note checks for NULL before using macro. strdup failure would set note_actions[note] to NULL, then checked. Safe.
• FIFO write errors silently ignored – no crash.

3. Memory Management

• note_actions[] strings are freed on every script_load write and on cleanup (script_cleanup called in tui_cleanup). No leak.
• Audio loop buffer (loop_data_t) is embedded in scene_t – no heap allocation.
• Save path uses malloc/free correctly; freed after write.
• Log file pointer is closed at exit.

4. Thread Safety

• All scene_t fields accessed from both threads are atomic (state, prev_state, record_pos, loop_count, playback_pos). Correct.
• channel_t.active, channel_t.save_ring are atomic. Correct.
• Save sequence: set active=0, sleep 500 ms, copy buffer, set active=1. The sleep guarantees the RT thread has seen the deactivation. No race.
• Logging mutex acquired only outside audio thread – fine.
• FIFO writes from multiple threads are not serialized but write to a FIFO is atomic for writes ≤ PIPE_BUF (4096 bytes). Our messages are smaller. Safe.

5. Performance

• Audio buffer processing uses simple loops with no function calls. nframes is typically 64‑256 – fine.
• state transitions check prev_state each callback – cheap.
• Save mechanism: 500 ms pause may cause one xrun. Acceptable for a prototype.
• Main loop sleep 50 ms ensures low CPU usage.

6. Architectural Soundness

• Good: Clear separation between engine (real‑time audio) and client (UI, plugin management). Communication via FIFO files.
• Weakness: Three command queues (cmd_queue, cmd_queue_main_midi, cmd_queue_main_fifo) are redundant – all feed exec_command. Could consolidate.
• Weakness: Carla integration tied to the engine’s JACK client. A separate Carla engine instance would be cleaner.
• Strength: Script/macro system is simple text‑based and extensible. The notes FIFO allows any external controller to inject note numbers.
• Strength: Logging non‑intrusive and never used in real‑time path.

---

Overall, the codebase is functional and stable. All previously identified critical issues (channel bounds, memory leak, empty macro) have been fixed. Recommendations for further improvement:

• Replace three command queues with a single queue.
• Use a double‑buffer for save to eliminate the 500 ms pause.
• Consider mock objects for engine tests to remove JACK dependency.
• Add more unit tests for edge cases.

Evaluation date: 18 May 2026