template<template< class > class QueueT>
class audio_tools::AudioPlayerThreadSafe< QueueT >
Lock-free asynchronous control wrapper for AudioPlayer using a command queue.
Purpose Provides a minimal, thread-safe control surface (begin, end, next, setIndex, setPath, setVolume, setMuted, setActive) by enqueuing commands from any task and applying them inside copy() in the audio/render thread. This serializes all state changes without a mutex.
Contract
- Input: Reference to an existing AudioPlayer instance + queue capacity.
- API calls: enqueue a Command (non-blocking if underlying queue is configured with zero read/write wait). No direct state mutation happens in the caller's context.
- Execution: copy()/copy(bytes) drains the queue first (processCommands()) then performs audio transfer via AudioPlayer::copy(). Order is preserved (FIFO).
- Errors: enqueue() returns false if the queue is full (command dropped). Caller may retry later. No blocking is performed by this wrapper. Dequeue in processCommands() assumes the queue's read wait is non-blocking (e.g. QueueRTOS.setReadMaxWait(0)).
- Path lifetime: setPath(const char*) stores the pointer; caller must keep the memory valid until the command is consumed. If the path buffer is ephemeral, allocate/copy it externally or extend the Command to own storage (future enhancement).
Thread-safety model
- All public control methods are producer-only; they never touch the AudioPlayer directly.
- The audio thread (calling copy()) is the single consumer applying changes, preventing races.
- No mutexes or locks are used; correctness relies on queue's internal synchronization.
Callback / reentrancy guidance
- Avoid calling wrapper control methods from callbacks invoked by copy() (e.g. EOF callbacks) to prevent immediate feedback loops; schedule such actions from another task.
Template parameter
- QueueT: a queue class template <class T> providing: constructor(int
size,...), bool enqueue(T&), bool dequeue(T&). Example: QueueRTOS.
- Template Parameters
-
| QueueT | Queue class template taking a single type parameter (the command type). |
