Bela
Real-time, ultra-low-latency audio and sensor processing system for BeagleBone Black
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Macros | Typedefs | Functions
Auxiliary task support

Macros

#define BELA_AUDIO_PRIORITY   95
 

Typedefs

typedef void * AuxiliaryTask
 

Functions

AuxiliaryTask Bela_createAuxiliaryTask (void(*callback)(void *), int priority, const char *name, void *arg=NULL)
 Create a new auxiliary task. More...
 
int Bela_scheduleAuxiliaryTask (AuxiliaryTask task)
 Run an auxiliary task which has previously been created. More...
 
AuxiliaryTask Bela_runAuxiliaryTask (void(*callback)(void *), int priority=0, void *arg=nullptr)
 Create and start an AuxiliaryTask. More...
 
int Bela_startAuxiliaryTask (AuxiliaryTask task)
 Initialize an auxiliary task so that it can be scheduled. More...
 
int Bela_startAllAuxiliaryTasks ()
 
void Bela_stopAllAuxiliaryTasks ()
 
void Bela_deleteAllAuxiliaryTasks ()
 

Detailed Description

These functions are used to create separate real-time tasks (threads) which run at lower priority than the audio processing. They can be used, for example, for large time-consuming calculations which would take more than one audio frame length to process, or they could be used to communicate with external hardware when that communication might block or be delayed.

All auxiliary tasks used by the program should be created in setup(). The tasks can then be scheduled at will within the render() function.

Macro Definition Documentation

#define BELA_AUDIO_PRIORITY   95

Xenomai priority level for audio processing. Maximum possible priority is 99. In general, all auxiliary tasks should have a level lower than this unless for\ special purposes where the task needs to interrupt audio processing.

Typedef Documentation

typedef void* AuxiliaryTask

Auxiliary task variable. Auxiliary tasks are created using createAuxiliaryTask() and automatically cleaned up after cleanup() finishes.

Function Documentation

AuxiliaryTask Bela_createAuxiliaryTask ( void(*)(void *)  callback,
int  priority,
const char *  name,
void *  arg = NULL 
)

Create a new auxiliary task.

This function creates a new auxiliary task which, when scheduled, runs the function specified in the first argument. Note that the task does not run until scheduleAuxiliaryTask() is called. Auxiliary tasks should be created in setup() and never in render() itself.

The second argument specifies the real-time priority. Valid values are between 0 and 99, and usually should be lower than BELA_AUDIO_PRIORITY. Tasks with higher priority always preempt tasks with lower priority.

Parameters
callbackFunction which will be called each time the auxiliary task is scheduled, unless it is already running.
priorityXenomai priority level at which the task should run.
nameName for this task, which should be unique system-wide (no other running program should use this name).
argThe argument passed to the callback function.
Examples:
Audio/FFT-phase-vocoder/render.cpp, Audio/sample-streamer-multi/render.cpp, Audio/sample-streamer/render.cpp, Capelets/multiplexer-spectrum/render.cpp, Communication/Serial/render.cpp, Communication/Spi/render.cpp, Extras/oscillator-bank/render.cpp, Sensors/MPR121/render.cpp, terminal-only/filter-FIR/render.cpp, terminal-only/filter-IIR/render.cpp, and terminal-only/samples/render.cpp.
int Bela_scheduleAuxiliaryTask ( AuxiliaryTask  task)

Run an auxiliary task which has previously been created.

This function will schedule an auxiliary task to run.

If the task is already running, calling this function has no effect. If the task is not running (e.g.: a previous invocation has returned), the callback function defined in Bela_createAuxiliaryTask() will be called and it will be passed the arg pointer as its only parameter.

This function is typically called from render() to start a lower-priority task. The function will not run immediately, but only once any active higher priority tasks have finished.

Parameters
taskTask to schedule for running.
Returns
0 if the task was successfully scheduled, a positive error number otherwise. The most frequent error will be EBUSY, if the task was still running as a consequence of a previous call.
Examples:
Audio/FFT-phase-vocoder/render.cpp, Audio/sample-streamer-multi/render.cpp, Audio/sample-streamer/render.cpp, Capelets/multiplexer-spectrum/render.cpp, Communication/Serial/render.cpp, Communication/Spi/render.cpp, Extras/oscillator-bank/render.cpp, Sensors/MPR121/render.cpp, terminal-only/filter-FIR/render.cpp, terminal-only/filter-IIR/render.cpp, and terminal-only/samples/render.cpp.
AuxiliaryTask Bela_runAuxiliaryTask ( void(*)(void *)  callback,
int  priority = 0,
void *  arg = nullptr 
)

Create and start an AuxiliaryTask.

Effectively this is a shorthand for Bela_createAuxiliaryTask() followed by Bela_scheduleAuxiliaryTask(), with fewer parameters to make it easier to use.

Parameters
callbackthe function to run in the thread.
prioritythe priority of the thread. Defaults to 0.
argthe argument to be passed to the callback. Defaults to nullptr.
Returns
the AuxiliaryTask on success, so that it can be scheduled again later if needed, or 0 if an error occurred.
Examples:
Trill/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/craft-sound/render.cpp, Trill/craft-visual/render.cpp, Trill/custom-slider/render.cpp, Trill/flex-default/render.cpp, Trill/flex-visual/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, Trill/general-visual/render.cpp, Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/multiple-devices/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, Trill/square-multitouch/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.
int Bela_startAuxiliaryTask ( AuxiliaryTask  task)

Initialize an auxiliary task so that it can be scheduled.

User normally do not need to call this function.

This function will start an auxiliary task but will NOT schedule it. This means that the callback function associated with the task will NOT be executed.

It will also set a flag in the associate InternalAuxiliaryTask to flag the task as "started", so that successive calls to the same function for a given AuxiliaryTask have no effect. The user should never be required to call this function directly, as it is called by Bela_scheduleAuxiliaryTask if needed (e.g.: if a task is scheduled in setup() ) or immediately after starting the audio thread.

Parameters
taskTask to start.