PulseAudio 16.1

Threaded Main Loop

# Overview

The threaded main loop implementation is a special version of the primary main loop implementation (see Main Loop). For the basic design, see its documentation.

The added feature in the threaded main loop is that it spawns a new thread that runs the real main loop. This allows a synchronous application to use the asynchronous API without risking stalling the PulseAudio library.

# Creation

A pa_threaded_mainloop object is created using pa_threaded_mainloop_new(). This will only allocate the required structures though, so to use it the thread must also be started. This is done through pa_threaded_mainloop_start(), after which you can start using the main loop.

# Destruction

When the PulseAudio connection has been terminated, the thread must be stopped and the resources freed. Stopping the thread is done using pa_threaded_mainloop_stop(), which must be called without the lock (see below) held. When that function returns, the thread is stopped and the pa_threaded_mainloop object can be freed using pa_threaded_mainloop_free().

# Locking

Since the PulseAudio API doesn't allow concurrent accesses to objects, a locking scheme must be used to guarantee safe usage. The threaded main loop API provides such a scheme through the functions pa_threaded_mainloop_lock() and pa_threaded_mainloop_unlock().

The lock is recursive, so it's safe to use it multiple times from the same thread. Just make sure you call pa_threaded_mainloop_unlock() the same number of times you called pa_threaded_mainloop_lock().

The lock needs to be held whenever you call any PulseAudio function that uses an object associated with this main loop. Those objects include pa_mainloop, pa_context, pa_stream and pa_operation, and the various event objects (pa_io_event, pa_time_event, pa_defer_event). Make sure you do not hold on to the lock more than necessary though, as the threaded main loop stops while the lock is held.

Example:

void my_check_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
pa_stream_state_t state;
pa_threaded_mainloop_lock(m);
state = pa_stream_get_state(s);
pa_threaded_mainloop_unlock(m);
if (state == PA_STREAM_READY)
printf("Stream is ready!");
else
printf("Stream is not ready!");
}
PA_STREAM_READY
@ PA_STREAM_READY
The stream is established, you may pass audio data to it now.
Definition: def.h:71
pa_stream_state_t
enum pa_stream_state pa_stream_state_t
The state of a stream.
pa_stream
struct pa_stream pa_stream
An opaque stream for playback or recording.
Definition: stream.h:289
pa_stream_get_state
pa_stream_state_t pa_stream_get_state(const pa_stream *p)
Return the current state of the stream.
pa_threaded_mainloop_lock
void pa_threaded_mainloop_lock(pa_threaded_mainloop *m)
Lock the event loop object, effectively blocking the event loop thread from processing events.
pa_threaded_mainloop
struct pa_threaded_mainloop pa_threaded_mainloop
An opaque threaded main loop object.
Definition: thread-mainloop.h:248
pa_threaded_mainloop_unlock
void pa_threaded_mainloop_unlock(pa_threaded_mainloop *m)
Unlock the event loop object, inverse of pa_threaded_mainloop_lock().

# Callbacks

Callbacks in PulseAudio are asynchronous, so they require extra care when using them together with a threaded main loop.

The easiest way to turn the callback based operations into synchronous ones, is to simply wait for the callback to be called and continue from there. This is the approach chosen in PulseAudio's threaded API.

## Basic callbacks

For the basic case, where all that is required is to wait for the callback to be invoked, the code should look something like this:

Example:

static void my_drain_callback(pa_stream *s, int success, void *userdata) {
pa_threaded_mainloop *m;
m = userdata;
assert(m);
pa_threaded_mainloop_signal(m, 0);
}
void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
pa_operation *o;
pa_threaded_mainloop_lock(m);
o = pa_stream_drain(s, my_drain_callback, m);
assert(o);
while (pa_operation_get_state(o) == PA_OPERATION_RUNNING)
pa_threaded_mainloop_wait(m);
pa_operation_unref(o);
pa_threaded_mainloop_unlock(m);
}
PA_OPERATION_RUNNING
@ PA_OPERATION_RUNNING
The operation is still running.
Definition: def.h:94
pa_operation_get_state
pa_operation_state_t pa_operation_get_state(const pa_operation *o)
Return the current status of the operation.
pa_operation
struct pa_operation pa_operation
An asynchronous operation object.
Definition: operation.h:33
pa_operation_unref
void pa_operation_unref(pa_operation *o)
Decrease the reference count by one.
pa_stream_drain
pa_operation * pa_stream_drain(pa_stream *s, pa_stream_success_cb_t cb, void *userdata)
Drain a playback stream.
pa_threaded_mainloop_wait
void pa_threaded_mainloop_wait(pa_threaded_mainloop *m)
Wait for an event to be signalled by the event loop thread.
pa_threaded_mainloop_signal
void pa_threaded_mainloop_signal(pa_threaded_mainloop *m, int wait_for_accept)
Signal all threads waiting for a signalling event in pa_threaded_mainloop_wait().

The main function, my_drain_stream_func(), will wait for the callback to be called using pa_threaded_mainloop_wait().

If your application is multi-threaded, then this waiting must be done inside a while loop. The reason for this is that multiple threads might be using pa_threaded_mainloop_wait() at the same time. Each thread must therefore verify that it was its callback that was invoked. Also the underlying OS synchronization primitives are usually not free of spurious wake-ups, so a pa_threaded_mainloop_wait() must be called within a loop even if you have only one thread waiting.

The callback, my_drain_callback(), indicates to the main function that it has been called using pa_threaded_mainloop_signal().

As you can see, pa_threaded_mainloop_wait() may only be called with the lock held. The same thing is true for pa_threaded_mainloop_signal(), but as the lock is held before the callback is invoked, you do not have to deal with that.

The functions will not dead lock because the wait function will release the lock before waiting and then regrab it once it has been signalled. For those of you familiar with threads, the behaviour is that of a condition variable.

## Data callbacks

For many callbacks, simply knowing that they have been called is insufficient. The callback also receives some data that is desired. To access this data safely, we must extend our example a bit:

static int * volatile drain_result = NULL;
static void my_drain_callback(pa_stream*s, int success, void *userdata) {
pa_threaded_mainloop *m;
m = userdata;
assert(m);
drain_result = &success;
pa_threaded_mainloop_signal(m, 1);
}
void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
pa_operation *o;
pa_threaded_mainloop_lock(m);
o = pa_stream_drain(s, my_drain_callback, m);
assert(o);
while (drain_result == NULL)
pa_threaded_mainloop_wait(m);
pa_operation_unref(o);
if (*drain_result)
printf("Success!");
else
printf("Bitter defeat...");
pa_threaded_mainloop_accept(m);
pa_threaded_mainloop_unlock(m);
}
pa_threaded_mainloop_accept
void pa_threaded_mainloop_accept(pa_threaded_mainloop *m)
Accept a signal from the event thread issued with pa_threaded_mainloop_signal().

The example is a bit silly as it would probably have been easier to just copy the contents of success, but for larger data structures this can be wasteful.

The difference here compared to the basic callback is the value 1 passed to pa_threaded_mainloop_signal() and the call to pa_threaded_mainloop_accept(). What will happen is that pa_threaded_mainloop_signal() will signal the main function and then wait. The main function is then free to use the data in the callback until pa_threaded_mainloop_accept() is called, which will allow the callback to continue.

Note that pa_threaded_mainloop_accept() must be called some time between exiting the while loop and unlocking the main loop! Failure to do so will result in a race condition. I.e. it is not ok to release the lock and regrab it before calling pa_threaded_mainloop_accept().

## Asynchronous callbacks

PulseAudio also has callbacks that are completely asynchronous, meaning that they can be called at any time. The threaded main loop API provides the locking mechanism to handle concurrent accesses, but nothing else. Applications will have to handle communication from the callback to the main program through their own mechanisms.

The callbacks that are completely asynchronous are:

- State callbacks for contexts, streams, etc.
- Subscription notifications