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_uniquestd::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_mutexpthread_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.
1---2name: audio-dsp-review3description: 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.4---56# Audio DSP Realtime Safety Review78> **The cardinal rule:** *If you don't know how long it will take, don't do it.*9>10> The audio callback has a hard deadline — typically 1–5ms per buffer. Miss it once and the11> user hears a glitch. The three categories of violations that cause this are: **allocations**,12> **locking**, and **system calls** — all of which can block for unbounded time.1314## Step 1 — Find the realtime context1516Identify the audio callback and every function it calls (transitively). Common names:17`processBlock`, `process`, `render`, `getNextAudioBlock`, `audioDeviceIOCallback`,18`AURenderCallback`, `JackProcessCallback`, and the output-stream closure in cpal/JUCE/PortAudio.1920## Step 2 — Scan for violations2122**Memory allocations** (allocator paths may lock, grow arenas, touch new pages, or run23unbounded bookkeeping):24- `new` / `delete` / `malloc` / `free` / `make_shared` / `make_unique`25- `std::string` construction, concatenation, `to_string()`26- Container growth: `vector::push_back` without pre-reserve, `map::operator[]` on new keys,27 `unordered_map::insert`, `deque::push_back`28- `std::function` with non-trivial captures (may allocate), throwing exceptions2930**Locking** (priority inversion: the low-priority UI thread holds the lock your audio thread needs):31- `std::mutex`, `lock_guard`, `unique_lock`, `scoped_lock`, `shared_mutex`32- `pthread_mutex_lock`, `pthread_rwlock_*`33- `condition_variable::wait()`, `future::get()`, `semaphore::acquire()`34- **`std::mutex::try_lock()` + RAII wrapper** — `try_lock()` itself is non-blocking, but the35 RAII destructor calls `unlock()`, which does a system call to wake waiting threads.36 Not realtime-safe. Same for `std::unique_lock(mtx, std::try_to_lock)`.37- Spinlocks without exponential back-off on the non-audio thread — busy-wait burns CPU,38 causes starvation under contention, and drains battery on mobile devices.39 If you must use a spinlock: audio thread calls only `try_lock()` + fallback;40 non-audio thread uses progressive back-off (spin → `_mm_pause()` → batched pauses → occasional yield).4142**System calls / blocking I/O** (kernel transitions stall for unbounded time):43- `printf`, `fprintf`, `cout`, `cerr`, `DBG()` (JUCE debug), `syslog`, `os_log`44- File I/O: `fopen`, `fclose`, `fread`, `fwrite`, `open`, `read`, `write`45- `sleep`, `usleep`, `nanosleep`, `std::this_thread::sleep_for`, `yield`46- Network: `connect`, `send`, `recv`, `select`47- `std::system()`, `assert()` (in debug builds: prints + aborts)4849**Warnings** (flag but don't block):50- First-touch page faults — allocate and pre-touch buffers in `prepareToPlay`51- Denormal floats — missing `ScopedNoDenormals` or `_MM_SET_FLUSH_ZERO_MODE` causes 100× slowdown52- `std::rand()` — uses a global lock on some implementations5354## Step 3 — Write the review5556```57## Audio Realtime Safety Review: `[file / function]`5859### Verdict60[Safe | Has critical violations | Warnings only] — [one sentence summary]6162### Critical Violations63**[Category]: [description]**64`file:line` — `offending code`65Why: [one sentence on the realtime risk]66Fix: [concrete suggestion]6768### Warnings69[same format]7071### What's Done Well72[correct patterns observed — pre-allocation, atomics, lock-free queues, etc.]7374### Recommended Fixes (priority order)751. ...76```7778## Quick fix table7980| Violation | Realtime-safe alternative |81|-----------|--------------------------|82| `std::mutex` for shared state | Lock-free `std::atomic<T>` for scalars after checking `is_lock_free()`; SPSC lock-free queue for structs |83| `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 |84| 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()` |85| `new`/`delete` in callback | Allocate in `prepareToPlay`; use pre-allocated pool or ring buffer |86| `printf`/`DBG()` | Write to a lock-free ring buffer; drain from a background thread |87| `std::string` ops | `std::array<char,N>` + `snprintf`; format on UI thread |88| `vector` growing | `reserve()` on init; fixed-capacity container (`etl::vector`, `heapless::Vec`) |89| `map::operator[]` insertion | `find()` + pre-populate; or `std::array` with index lookup |90| Exception throwing | Validate in `prepareToPlay`; use error codes; never throw from callback |91| `std::function` w/ captures | Function pointer + `void*`; or pre-store as member |9293For deeper patterns (JUCE-specific, VST3, CLAP, Rust/cpal, Web Audio) see94`references/realtime-violations.md`.
kunitoki