audio-dsp-review

name

audio-dsp-review

description

Reviews audio DSP and audio processing code for realtime safety violations. Use whenever the user asks to review, audit, or check audio processing code — including plugin process callbacks, audio engine render functions, DSP implementations, or any code that runs on the audio thread. Trigger on phrases like "review my processBlock", "check this DSP code", "is this safe for the audio thread?", "review my JUCE plugin", or when you see an audio callback and spot potential realtime violations. Flag issues proactively even when the user hasn't explicitly asked for a review.

Audio DSP Realtime Safety Review

The cardinal rule: If you don't know how long it will take, don't do it.

The audio callback has a hard deadline — typically 1–5ms per buffer. Miss it once and the user hears a glitch. The three categories of violations that cause this are: allocations, locking, and system calls — all of which can block for unbounded time.

Step 1 — Find the realtime context

Identify the audio callback and every function it calls (transitively). Common names: processBlock, process, render, getNextAudioBlock, audioDeviceIOCallback, AURenderCallback, JackProcessCallback, and the output-stream closure in cpal/JUCE/PortAudio.

Step 2 — Scan for violations

Memory allocations (allocator paths may lock, grow arenas, touch new pages, or run unbounded bookkeeping):

• new / delete / malloc / free / make_shared / make_unique
• std::string construction, concatenation, to_string()
• Container growth: vector::push_back without pre-reserve, map::operator[] on new keys, unordered_map::insert, deque::push_back
• std::function with non-trivial captures (may allocate), throwing exceptions

Locking (priority inversion: the low-priority UI thread holds the lock your audio thread needs):

• std::mutex, lock_guard, unique_lock, scoped_lock, shared_mutex
• pthread_mutex_lock, pthread_rwlock_*
• condition_variable::wait(), future::get(), semaphore::acquire()
• std::mutex::try_lock() + RAII wrapper — try_lock() itself is non-blocking, but the RAII destructor calls unlock(), which does a system call to wake waiting threads. Not realtime-safe. Same for std::unique_lock(mtx, std::try_to_lock).
• Spinlocks without exponential back-off on the non-audio thread — busy-wait burns CPU, causes starvation under contention, and drains battery on mobile devices. If you must use a spinlock: audio thread calls only try_lock() + fallback; non-audio thread uses progressive back-off (spin → _mm_pause() → batched pauses → occasional yield).

System calls / blocking I/O (kernel transitions stall for unbounded time):

• printf, fprintf, cout, cerr, DBG() (JUCE debug), syslog, os_log
• File I/O: fopen, fclose, fread, fwrite, open, read, write
• sleep, usleep, nanosleep, std::this_thread::sleep_for, yield
• Network: connect, send, recv, select
• std::system(), assert() (in debug builds: prints + aborts)

Warnings (flag but don't block):

• First-touch page faults — allocate and pre-touch buffers in prepareToPlay
• Denormal floats — missing ScopedNoDenormals or _MM_SET_FLUSH_ZERO_MODE causes 100× slowdown
• std::rand() — uses a global lock on some implementations

Step 3 — Write the review

## Audio Realtime Safety Review: `[file / function]`

### Verdict
[Safe | Has critical violations | Warnings only] — [one sentence summary]

### Critical Violations
**[Category]: [description]**
`file:line` — `offending code`
Why: [one sentence on the realtime risk]
Fix: [concrete suggestion]

### Warnings
[same format]

### What's Done Well
[correct patterns observed — pre-allocation, atomics, lock-free queues, etc.]

### Recommended Fixes (priority order)
1. ...

Quick fix table

Violation	Realtime-safe alternative
std::mutex for shared state	Lock-free std::atomic<T> for scalars after checking is_lock_free(); SPSC lock-free queue for structs
std::mutex::try_lock() + RAII	unlock() in destructor does a syscall — not safe. Use std::atomic_flag spinlock with try_lock() only on audio thread + fallback
Spinlock with busy-wait on non-audio thread	Progressive back-off: spin 5× → _mm_pause() 10× → batched 10× _mm_pause() → occasional std::this_thread::yield()
new/delete in callback	Allocate in prepareToPlay; use pre-allocated pool or ring buffer
printf/DBG()	Write to a lock-free ring buffer; drain from a background thread
std::string ops	std::array<char,N> + snprintf; format on UI thread
vector growing	reserve() on init; fixed-capacity container (etl::vector, heapless::Vec)
map::operator[] insertion	find() + pre-populate; or std::array with index lookup
Exception throwing	Validate in prepareToPlay; use error codes; never throw from callback
std::function w/ captures	Function pointer + void*; or pre-store as member

For deeper patterns (JUCE-specific, VST3, CLAP, Rust/cpal, Web Audio) see references/realtime-violations.md.