318 lines
12 KiB
C++
318 lines
12 KiB
C++
|
#ifndef foothreadmainloophfoo
|
||
|
|
#define foothreadmainloophfoo
|
||
|
|
|
||
|
|
/***
|
||
|
|
This file is part of PulseAudio.
|
||
|
|
|
||
|
|
Copyright 2006 Lennart Poettering
|
||
|
|
Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
|
||
|
|
|
||
|
|
PulseAudio is free software; you can redistribute it and/or modify
|
||
|
|
it under the terms of the GNU Lesser General Public License as published
|
||
|
|
by the Free Software Foundation; either version 2.1 of the License,
|
||
|
|
or (at your option) any later version.
|
||
|
|
|
||
|
|
PulseAudio is distributed in the hope that it will be useful, but
|
||
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
|
|
General Public License for more details.
|
||
|
|
|
||
|
|
You should have received a copy of the GNU Lesser General Public License
|
||
|
|
along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
|
||
|
|
***/
|
||
|
|
|
||
|
|
#include <pulse/mainloop-api.h>
|
||
|
|
#include <pulse/cdecl.h>
|
||
|
|
#include <pulse/version.h>
|
||
|
|
|
||
|
|
PA_C_DECL_BEGIN
|
||
|
|
|
||
|
|
/** \page threaded_mainloop Threaded Main Loop
|
||
|
|
*
|
||
|
|
* \section overv_sec Overview
|
||
|
|
*
|
||
|
|
* The threaded main loop implementation is a special version of the primary
|
||
|
|
* main loop implementation (see \ref mainloop). 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 to stall the PulseAudio library.
|
||
|
|
*
|
||
|
|
* \section creat_sec 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.
|
||
|
|
*
|
||
|
|
* \section destr_sec 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().
|
||
|
|
*
|
||
|
|
* \section lock_sec 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. 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:
|
||
|
|
*
|
||
|
|
* \code
|
||
|
|
* 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!");
|
||
|
|
* }
|
||
|
|
* \endcode
|
||
|
|
*
|
||
|
|
* \section cb_sec 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.
|
||
|
|
*
|
||
|
|
* \subsection basic_subsec 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:
|
||
|
|
*
|
||
|
|
* \code
|
||
|
|
* 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);
|
||
|
|
* }
|
||
|
|
* \endcode
|
||
|
|
*
|
||
|
|
* 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.
|
||
|
|
*
|
||
|
|
* \subsection data_subsec 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:
|
||
|
|
*
|
||
|
|
* \code
|
||
|
|
* 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);
|
||
|
|
* }
|
||
|
|
* \endcode
|
||
|
|
*
|
||
|
|
* 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().
|
||
|
|
*
|
||
|
|
* \subsection async_subsec 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:
|
||
|
|
*
|
||
|
|
* \li State callbacks for contexts, streams, etc.
|
||
|
|
* \li Subscription notifications
|
||
|
|
*/
|
||
|
|
|
||
|
|
/** \file
|
||
|
|
*
|
||
|
|
* A thread based event loop implementation based on pa_mainloop. The
|
||
|
|
* event loop is run in a helper thread in the background. A few
|
||
|
|
* synchronization primitives are available to access the objects
|
||
|
|
* attached to the event loop safely.
|
||
|
|
*
|
||
|
|
* See also \subpage threaded_mainloop
|
||
|
|
*/
|
||
|
|
|
||
|
|
/** An opaque threaded main loop object */
|
||
|
|
typedef struct pa_threaded_mainloop pa_threaded_mainloop;
|
||
|
|
|
||
|
|
/** Allocate a new threaded main loop object. You have to call
|
||
|
|
* pa_threaded_mainloop_start() before the event loop thread starts
|
||
|
|
* running. */
|
||
|
|
pa_threaded_mainloop *pa_threaded_mainloop_new(void);
|
||
|
|
|
||
|
|
/** Free a threaded main loop object. If the event loop thread is
|
||
|
|
* still running, terminate it with pa_threaded_mainloop_stop()
|
||
|
|
* first. */
|
||
|
|
void pa_threaded_mainloop_free(pa_threaded_mainloop* m);
|
||
|
|
|
||
|
|
/** Start the event loop thread. */
|
||
|
|
int pa_threaded_mainloop_start(pa_threaded_mainloop *m);
|
||
|
|
|
||
|
|
/** Terminate the event loop thread cleanly. Make sure to unlock the
|
||
|
|
* mainloop object before calling this function. */
|
||
|
|
void pa_threaded_mainloop_stop(pa_threaded_mainloop *m);
|
||
|
|
|
||
|
|
/** Lock the event loop object, effectively blocking the event loop
|
||
|
|
* thread from processing events. You can use this to enforce
|
||
|
|
* exclusive access to all objects attached to the event loop. This
|
||
|
|
* lock is recursive. This function may not be called inside the event
|
||
|
|
* loop thread. Events that are dispatched from the event loop thread
|
||
|
|
* are executed with this lock held. */
|
||
|
|
void pa_threaded_mainloop_lock(pa_threaded_mainloop *m);
|
||
|
|
|
||
|
|
/** Unlock the event loop object, inverse of pa_threaded_mainloop_lock(). */
|
||
|
|
void pa_threaded_mainloop_unlock(pa_threaded_mainloop *m);
|
||
|
|
|
||
|
|
/** Wait for an event to be signalled by the event loop thread. You
|
||
|
|
* can use this to pass data from the event loop thread to the main
|
||
|
|
* thread in a synchronized fashion. This function may not be called
|
||
|
|
* inside the event loop thread. Prior to this call the event loop
|
||
|
|
* object needs to be locked using pa_threaded_mainloop_lock(). While
|
||
|
|
* waiting the lock will be released. Immediately before returning it
|
||
|
|
* will be acquired again. This function may spuriously wake up even
|
||
|
|
* without pa_threaded_mainloop_signal() being called. You need to
|
||
|
|
* make sure to handle that! */
|
||
|
|
void pa_threaded_mainloop_wait(pa_threaded_mainloop *m);
|
||
|
|
|
||
|
|
/** Signal all threads waiting for a signalling event in
|
||
|
|
* pa_threaded_mainloop_wait(). If wait_for_accept is non-zero, do
|
||
|
|
* not return before the signal was accepted by a
|
||
|
|
* pa_threaded_mainloop_accept() call. While waiting for that condition
|
||
|
|
* the event loop object is unlocked. */
|
||
|
|
void pa_threaded_mainloop_signal(pa_threaded_mainloop *m, int wait_for_accept);
|
||
|
|
|
||
|
|
/** Accept a signal from the event thread issued with
|
||
|
|
* pa_threaded_mainloop_signal(). This call should only be used in
|
||
|
|
* conjunction with pa_threaded_mainloop_signal() with a non-zero
|
||
|
|
* wait_for_accept value. */
|
||
|
|
void pa_threaded_mainloop_accept(pa_threaded_mainloop *m);
|
||
|
|
|
||
|
|
/** Return the return value as specified with the main loop's
|
||
|
|
* pa_mainloop_quit() routine. */
|
||
|
|
int pa_threaded_mainloop_get_retval(pa_threaded_mainloop *m);
|
||
|
|
|
||
|
|
/** Return the main loop abstraction layer vtable for this main loop.
|
||
|
|
* There is no need to free this object as it is owned by the loop
|
||
|
|
* and is destroyed when the loop is freed. */
|
||
|
|
pa_mainloop_api* pa_threaded_mainloop_get_api(pa_threaded_mainloop*m);
|
||
|
|
|
||
|
|
/** Returns non-zero when called from within the event loop thread. \since 0.9.7 */
|
||
|
|
int pa_threaded_mainloop_in_thread(pa_threaded_mainloop *m);
|
||
|
|
|
||
|
|
/** Sets the name of the thread. \since 5.0 */
|
||
|
|
void pa_threaded_mainloop_set_name(pa_threaded_mainloop *m, const char *name);
|
||
|
|
|
||
|
|
PA_C_DECL_END
|
||
|
|
|
||
|
|
#endif
|