AudioPlayerThreadSafe< QueueT > Class Template Reference

Lock-free asynchronous control wrapper for AudioPlayer using a command queue. More...

#include <AudioPlayerThreadSafe.h>

Public Member Functions
	AudioPlayerThreadSafe (AudioPlayer &p, QueueT< AudioPlayerCommand > &queue)
	Construct an async-control wrapper around an AudioPlayer.
bool	begin (int index=0, bool isActive=true)
size_t	copy ()
size_t	copy (size_t bytes)
void	end ()
bool	next (int offset=1)
void	setActive (bool active)
bool	setIndex (int idx)
bool	setMuted (bool muted)
bool	setPath (const char *path)
bool	setVolume (float v)

Detailed Description

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).

Constructor & Destructor Documentation

AudioPlayerThreadSafe()

template<template< class > class QueueT>

AudioPlayerThreadSafe ( AudioPlayer & p, QueueT< AudioPlayerCommand > & queue )

inline

Construct an async-control wrapper around an AudioPlayer.

Parameters

p	Underlying AudioPlayer to protect
queueSize	Capacity of the internal command queue

Member Function Documentation

begin()

template<template< class > class QueueT>

bool begin ( int index = 0, bool isActive = true )

inline

copy() [1/2]

template<template< class > class QueueT>

size_t copy ( )

inline

copy() [2/2]

template<template< class > class QueueT>

size_t copy ( size_t bytes )

inline

end()

template<template< class > class QueueT>

void end ( )

inline

next()

template<template< class > class QueueT>

bool next ( int offset = 1 )

inline

setActive()

template<template< class > class QueueT>

void setActive ( bool active )

inline

setIndex()

template<template< class > class QueueT>

bool setIndex ( int idx )

inline

setMuted()

template<template< class > class QueueT>

bool setMuted ( bool muted )

inline

setPath()

template<template< class > class QueueT>

bool setPath ( const char * path )

inline

setVolume()

template<template< class > class QueueT>

bool setVolume ( float v )

inline

---

The documentation for this class was generated from the following file:

• src/AudioTools/Concurrency/AudioPlayerThreadSafe.h