src/pulse/thread-mainloop.h

   1 #ifndef foothreadmainloophfoo
   2 #define foothreadmainloophfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2006 Lennart Poettering
   8   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
   9
  10   PulseAudio is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU Lesser General Public License as published
  12   by the Free Software Foundation; either version 2.1 of the License,
  13   or (at your option) any later version.
  14
  15   PulseAudio is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with PulseAudio; if not, write to the Free Software
  22   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  23   USA.
  24 ***/
  25
  26 #include <pulse/mainloop-api.h>
  27 #include <pulse/cdecl.h>
  28 #include <pulse/version.h>
  29
  30 PA_C_DECL_BEGIN
  31
  32 /** \page threaded_mainloop Threaded Main Loop
  33  *
  34  * \section overv_sec Overview
  35  *
  36  * The threaded main loop implementation is a special version of the primary
  37  * main loop implementation (see \ref mainloop). For the basic design, see
  38  * its documentation.
  39  *
  40  * The added feature in the threaded main loop is that it spawns a new thread
  41  * that runs the real main loop. This allows a synchronous application to use
  42  * the asynchronous API without risking to stall the PulseAudio library.
  43  *
  44  * \section creat_sec Creation
  45  *
  46  * A pa_threaded_mainloop object is created using pa_threaded_mainloop_new().
  47  * This will only allocate the required structures though, so to use it the
  48  * thread must also be started. This is done through
  49  * pa_threaded_mainloop_start(), after which you can start using the main loop.
  50  *
  51  * \section destr_sec Destruction
  52  *
  53  * When the PulseAudio connection has been terminated, the thread must be
  54  * stopped and the resources freed. Stopping the thread is done using
  55  * pa_threaded_mainloop_stop(), which must be called without the lock (see
  56  * below) held. When that function returns, the thread is stopped and the
  57  * pa_threaded_mainloop object can be freed using pa_threaded_mainloop_free().
  58  *
  59  * \section lock_sec Locking
  60  *
  61  * Since the PulseAudio API doesn't allow concurrent accesses to objects,
  62  * a locking scheme must be used to guarantee safe usage. The threaded main
  63  * loop API provides such a scheme through the functions
  64  * pa_threaded_mainloop_lock() and pa_threaded_mainloop_unlock().
  65  *
  66  * The lock is recursive, so it's safe to use it multiple times from the same
  67  * thread. Just make sure you call pa_threaded_mainloop_unlock() the same
  68  * number of times you called pa_threaded_mainloop_lock().
  69  *
  70  * The lock needs to be held whenever you call any PulseAudio function that
  71  * uses an object associated with this main loop. Make sure you do not hold
  72  * on to the lock more than necessary though, as the threaded main loop stops
  73  * while the lock is held.
  74  *
  75  * Example:
  76  *
  77  * \code
  78  * void my_check_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
  79  *     pa_stream_state_t state;
  80  *
  81  *     pa_threaded_mainloop_lock(m);
  82  *
  83  *     state = pa_stream_get_state(s);
  84  *
  85  *     pa_threaded_mainloop_unlock(m);
  86  *
  87  *     if (state == PA_STREAM_READY)
  88  *         printf("Stream is ready!");
  89  *     else
  90  *         printf("Stream is not ready!");
  91  * }
  92  * \endcode
  93  *
  94  * \section cb_sec Callbacks
  95  *
  96  * Callbacks in PulseAudio are asynchronous, so they require extra care when
  97  * using them together with a threaded main loop.
  98  *
  99  * The easiest way to turn the callback based operations into synchronous
 100  * ones, is to simply wait for the callback to be called and continue from
 101  * there. This is the approach chosen in PulseAudio's threaded API.
 102  *
 103  * \subsection basic_subsec Basic callbacks
 104  *
 105  * For the basic case, where all that is required is to wait for the callback
 106  * to be invoked, the code should look something like this:
 107  *
 108  * Example:
 109  *
 110  * \code
 111  * static void my_drain_callback(pa_stream *s, int success, void *userdata) {
 112  *     pa_threaded_mainloop *m;
 113  *
 114  *     m = userdata;
 115  *     assert(m);
 116  *
 117  *     pa_threaded_mainloop_signal(m, 0);
 118  * }
 119  *
 120  * void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
 121  *     pa_operation *o;
 122  *
 123  *     pa_threaded_mainloop_lock(m);
 124  *
 125  *     o = pa_stream_drain(s, my_drain_callback, m);
 126  *     assert(o);
 127  *
 128  *     while (pa_operation_get_state(o) == PA_OPERATION_RUNNING)
 129  *         pa_threaded_mainloop_wait(m);
 130  *
 131  *     pa_operation_unref(o);
 132  *
 133  *     pa_threaded_mainloop_unlock(m);
 134  * }
 135  * \endcode
 136  *
 137  * The main function, my_drain_stream_func(), will wait for the callback to
 138  * be called using pa_threaded_mainloop_wait().
 139  *
 140  * If your application is multi-threaded, then this waiting must be
 141  * done inside a while loop. The reason for this is that multiple
 142  * threads might be using pa_threaded_mainloop_wait() at the same
 143  * time. Each thread must therefore verify that it was its callback
 144  * that was invoked. Also the underlying OS synchronization primitives
 145  * are usually not free of spurious wake-ups, so a
 146  * pa_threaded_mainloop_wait() must be called within a loop even if
 147  * you have only one thread waiting.
 148  *
 149  * The callback, my_drain_callback(), indicates to the main function that it
 150  * has been called using pa_threaded_mainloop_signal().
 151  *
 152  * As you can see, pa_threaded_mainloop_wait() may only be called with
 153  * the lock held. The same thing is true for pa_threaded_mainloop_signal(),
 154  * but as the lock is held before the callback is invoked, you do not have to
 155  * deal with that.
 156  *
 157  * The functions will not dead lock because the wait function will release
 158  * the lock before waiting and then regrab it once it has been signaled.
 159  * For those of you familiar with threads, the behaviour is that of a
 160  * condition variable.
 161  *
 162  * \subsection data_subsec Data callbacks
 163  *
 164  * For many callbacks, simply knowing that they have been called is
 165  * insufficient. The callback also receives some data that is desired. To
 166  * access this data safely, we must extend our example a bit:
 167  *
 168  * \code
 169  * static int *drain_result;
 170  *
 171  * static void my_drain_callback(pa_stream*s, int success, void *userdata) {
 172  *     pa_threaded_mainloop *m;
 173  *
 174  *     m = userdata;
 175  *     assert(m);
 176  *
 177  *     drain_result = &success;
 178  *
 179  *     pa_threaded_mainloop_signal(m, 1);
 180  * }
 181  *
 182  * void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
 183  *     pa_operation *o;
 184  *
 185  *     pa_threaded_mainloop_lock(m);
 186  *
 187  *     o = pa_stream_drain(s, my_drain_callback, m);
 188  *     assert(o);
 189  *
 190  *     while (pa_operation_get_state(o) == PA_OPERATION_RUNNING)
 191  *         pa_threaded_mainloop_wait(m);
 192  *
 193  *     pa_operation_unref(o);
 194  *
 195  *     if (*drain_result)
 196  *         printf("Success!");
 197  *     else
 198  *         printf("Bitter defeat...");
 199  *
 200  *     pa_threaded_mainloop_accept(m);
 201  *
 202  *     pa_threaded_mainloop_unlock(m);
 203  * }
 204  * \endcode
 205  *
 206  * The example is a bit silly as it would probably have been easier to just
 207  * copy the contents of success, but for larger data structures this can be
 208  * wasteful.
 209  *
 210  * The difference here compared to the basic callback is the 1 sent to
 211  * pa_threaded_mainloop_signal() and the call to
 212  * pa_threaded_mainloop_accept(). What will happen is that
 213  * pa_threaded_mainloop_signal() will signal the main function and then stop.
 214  * The main function is then free to use the data in the callback until
 215  * pa_threaded_mainloop_accept() is called, which will allow the callback
 216  * to continue.
 217  *
 218  * Note that pa_threaded_mainloop_accept() must be called some time between
 219  * exiting the while loop and unlocking the main loop! Failure to do so will
 220  * result in a race condition. I.e. it is not ok to release the lock and
 221  * regrab it before calling pa_threaded_mainloop_accept().
 222  *
 223  * \subsection async_subsec Asynchronous callbacks
 224  *
 225  * PulseAudio also has callbacks that are completely asynchronous, meaning
 226  * that they can be called at any time. The threading main loop API provides
 227  * the locking mechanism to handle concurrent accesses, but nothing else.
 228  * Applications will have to handle communication from the callback to the
 229  * main program through some own system.
 230  *
 231  * The callbacks that are completely asynchronous are:
 232  *
 233  * \li State callbacks for contexts, streams, etc.
 234  * \li Subscription notifications
 235  */
 236
 237 /** \file
 238  *
 239  * A thread based event loop implementation based on pa_mainloop. The
 240  * event loop is run in a helper thread in the background. A few
 241  * synchronization primitives are available to access the objects
 242  * attached to the event loop safely. */
 243
 244 /** An opaque threaded main loop object */
 245 typedef struct pa_threaded_mainloop pa_threaded_mainloop;
 246
 247 /** Allocate a new threaded main loop object. You have to call
 248  * pa_threaded_mainloop_start() before the event loop thread starts
 249  * running. */
 250 pa_threaded_mainloop *pa_threaded_mainloop_new(void);
 251
 252 /** Free a threaded main loop object. If the event loop thread is
 253  * still running, it is terminated using pa_threaded_mainloop_stop()
 254  * first. */
 255 void pa_threaded_mainloop_free(pa_threaded_mainloop* m);
 256
 257 /** Start the event loop thread. */
 258 int pa_threaded_mainloop_start(pa_threaded_mainloop *m);
 259
 260 /** Terminate the event loop thread cleanly. Make sure to unlock the
 261  * mainloop object before calling this function. */
 262 void pa_threaded_mainloop_stop(pa_threaded_mainloop *m);
 263
 264 /** Lock the event loop object, effectively blocking the event loop
 265  * thread from processing events. You can use this to enforce
 266  * exclusive access to all objects attached to the event loop. This
 267  * lock is recursive. This function may not be called inside the event
 268  * loop thread. Events that are dispatched from the event loop thread
 269  * are executed with this lock held. */
 270 void pa_threaded_mainloop_lock(pa_threaded_mainloop *m);
 271
 272 /** Unlock the event loop object, inverse of pa_threaded_mainloop_lock() */
 273 void pa_threaded_mainloop_unlock(pa_threaded_mainloop *m);
 274
 275 /** Wait for an event to be signalled by the event loop thread. You
 276  * can use this to pass data from the event loop thread to the main
 277  * thread in synchronized fashion. This function may not be called
 278  * inside the event loop thread. Prior to this call the event loop
 279  * object needs to be locked using pa_threaded_mainloop_lock(). While
 280  * waiting the lock will be released, immediately before returning it
 281  * will be acquired again. This function may spuriously wake up even
 282  * without _signal() being called. You need to make sure to handle
 283  * that! */
 284 void pa_threaded_mainloop_wait(pa_threaded_mainloop *m);
 285
 286 /** Signal all threads waiting for a signalling event in
 287  * pa_threaded_mainloop_wait(). If wait_for_release is non-zero, do
 288  * not return before the signal was accepted by a
 289  * pa_threaded_mainloop_accept() call. While waiting for that condition
 290  * the event loop object is unlocked. */
 291 void pa_threaded_mainloop_signal(pa_threaded_mainloop *m, int wait_for_accept);
 292
 293 /** Accept a signal from the event thread issued with
 294  * pa_threaded_mainloop_signal(). This call should only be used in
 295  * conjunction with pa_threaded_mainloop_signal() with a non-zero
 296  * wait_for_accept value.  */
 297 void pa_threaded_mainloop_accept(pa_threaded_mainloop *m);
 298
 299 /** Return the return value as specified with the main loop's quit() routine. */
 300 int pa_threaded_mainloop_get_retval(pa_threaded_mainloop *m);
 301
 302 /** Return the abstract main loop abstraction layer vtable for this
 303     main loop. No need of freeing the API as it is owned by the loop
 304     and it is destroyed when this dies */
 305 pa_mainloop_api* pa_threaded_mainloop_get_api(pa_threaded_mainloop*m);
 306
 307 /** Returns non-zero when called from withing the event loop thread. \since 0.9.7 */
 308 int pa_threaded_mainloop_in_thread(pa_threaded_mainloop *m);
 309
 310 PA_C_DECL_END
 311
 312 #endif