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 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 = (pa_threaded_mainloop*)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) != OPERATION_DONE)
 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 done
 141  * inside a while loop. The reason for this is that multiple threads might be
 142  * using pa_threaded_mainloop_wait() at the same time. Each thread must
 143  * therefore verify that it was its callback that was invoked.
 144  *
 145  * The callback, my_drain_callback(), indicates to the main function that it
 146  * has been called using pa_threaded_mainloop_signal().
 147  *
 148  * As you can see, both pa_threaded_mainloop_wait() may only be called with
 149  * the lock held. The same thing is true for pa_threaded_mainloop_signal(),
 150  * but as the lock is held before the callback is invoked, you do not have to
 151  * deal with that.
 152  *
 153  * The functions will not dead lock because the wait function will release
 154  * the lock before waiting and then regrab it once it has been signaled.
 155  * For those of you familiar with threads, the behaviour is that of a
 156  * condition variable.
 157  *
 158  * \subsection data_subsec Data callbacks
 159  *
 160  * For many callbacks, simply knowing that they have been called is
 161  * insufficient. The callback also receives some data that is desired. To
 162  * access this data safely, we must extend our example a bit:
 163  *
 164  * \code
 165  * static int *drain_result;
 166  *
 167  * static void my_drain_callback(pa_stream*s, int success, void *userdata) {
 168  *     pa_threaded_mainloop *m;
 169  *
 170  *     m = (pa_threaded_mainloop*)userdata;
 171  *     assert(m);
 172  *
 173  *     drain_result = &success;
 174  *
 175  *     pa_threaded_mainloop_signal(m, 1);
 176  * }
 177  *
 178  * void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
 179  *     pa_operation *o;
 180  *
 181  *     pa_threaded_mainloop_lock(m);
 182  *
 183  *     o = pa_stream_drain(s, my_drain_callback, m);
 184  *     assert(o);
 185  *
 186  *     while (pa_operation_get_state(o) != OPERATION_DONE)
 187  *         pa_threaded_mainloop_wait(m);
 188  *
 189  *     pa_operation_unref(o);
 190  *
 191  *     if (*drain_result)
 192  *         printf("Success!");
 193  *     else
 194  *         printf("Bitter defeat...");
 195  *
 196  *     pa_threaded_mainloop_accept(m);
 197  *
 198  *     pa_threaded_mainloop_unlock(m);
 199  * }
 200  * \endcode
 201  *
 202  * The example is a bit silly as it would probably have been easier to just
 203  * copy the contents of success, but for larger data structures this can be
 204  * wasteful.
 205  *
 206  * The difference here compared to the basic callback is the 1 sent to
 207  * pa_threaded_mainloop_signal() and the call to
 208  * pa_threaded_mainloop_accept(). What will happen is that
 209  * pa_threaded_mainloop_signal() will signal the main function and then stop.
 210  * The main function is then free to use the data in the callback until
 211  * pa_threaded_mainloop_accept() is called, which will allow the callback
 212  * to continue.
 213  *
 214  * Note that pa_threaded_mainloop_accept() must be called some time between
 215  * exiting the while loop and unlocking the main loop! Failure to do so will
 216  * result in a race condition. I.e. it is not ok to release the lock and
 217  * regrab it before calling pa_threaded_mainloop_accept().
 218  *
 219  * \subsection async_subsec Asynchronous callbacks
 220  *
 221  * PulseAudio also has callbacks that are completely asynchronous, meaning
 222  * that they can be called at any time. The threading main loop API provides
 223  * the locking mechanism to handle concurrent accesses, but nothing else.
 224  * Applications will have to handle communication from the callback to the
 225  * main program through some own system.
 226  *
 227  * The callbacks that are completely asynchronous are:
 228  *
 229  * \li State callbacks for contexts, streams, etc.
 230  * \li Subscription notifications
 231  */
 232
 233 /** \file
 234  *
 235  * A thread based event loop implementation based on pa_mainloop. The
 236  * event loop is run in a helper thread in the background. A few
 237  * synchronization primitives are available to access the objects
 238  * attached to the event loop safely. */
 239
 240 /** An opaque threaded main loop object */
 241 typedef struct pa_threaded_mainloop pa_threaded_mainloop;
 242
 243 /** Allocate a new threaded main loop object. You have to call
 244  * pa_threaded_mainloop_start() before the event loop thread starts
 245  * running. */
 246 pa_threaded_mainloop *pa_threaded_mainloop_new(void);
 247
 248 /** Free a threaded main loop object. If the event loop thread is
 249  * still running, it is terminated using pa_threaded_mainloop_stop()
 250  * first. */
 251 void pa_threaded_mainloop_free(pa_threaded_mainloop* m);
 252
 253 /** Start the event loop thread. */
 254 int pa_threaded_mainloop_start(pa_threaded_mainloop *m);
 255
 256 /** Terminate the event loop thread cleanly. Make sure to unlock the
 257  * mainloop object before calling this function. */
 258 void pa_threaded_mainloop_stop(pa_threaded_mainloop *m);
 259
 260 /** Lock the event loop object, effectively blocking the event loop
 261  * thread from processing events. You can use this to enforce
 262  * exclusive access to all objects attached to the event loop. This
 263  * lock is recursive. This function may not be called inside the event
 264  * loop thread. Events that are dispatched from the event loop thread
 265  * are executed with this lock held. */
 266 void pa_threaded_mainloop_lock(pa_threaded_mainloop *m);
 267
 268 /** Unlock the event loop object, inverse of pa_threaded_mainloop_lock() */
 269 void pa_threaded_mainloop_unlock(pa_threaded_mainloop *m);
 270
 271 /** Wait for an event to be signalled by the event loop thread. You
 272  * can use this to pass data from the event loop thread to the main
 273  * thread in synchronized fashion. This function may not be called
 274  * inside the event loop thread. Prior to this call the event loop
 275  * object needs to be locked using pa_threaded_mainloop_lock(). While
 276  * waiting the lock will be released, immediately before returning it
 277  * will be acquired again. */
 278 void pa_threaded_mainloop_wait(pa_threaded_mainloop *m);
 279
 280 /** Signal all threads waiting for a signalling event in
 281  * pa_threaded_mainloop_wait(). If wait_for_release is non-zero, do
 282  * not return before the signal was accepted by a
 283  * pa_threaded_mainloop_accept() call. While waiting for that condition
 284  * the event loop object is unlocked. */
 285 void pa_threaded_mainloop_signal(pa_threaded_mainloop *m, int wait_for_accept);
 286
 287 /** Accept a signal from the event thread issued with
 288  * pa_threaded_mainloop_signal(). This call should only be used in
 289  * conjunction with pa_threaded_mainloop_signal() with a non-zero
 290  * wait_for_accept value.  */
 291 void pa_threaded_mainloop_accept(pa_threaded_mainloop *m);
 292
 293 /** Return the return value as specified with the main loop's quit() routine. */
 294 int pa_threaded_mainloop_get_retval(pa_threaded_mainloop *m);
 295
 296 /** Return the abstract main loop abstraction layer vtable for this main loop. */
 297 pa_mainloop_api* pa_threaded_mainloop_get_api(pa_threaded_mainloop*m);
 298
 299 /** Returns non-zero when called from withing the event loop thread. \since 0.9.7 */
 300 int pa_threaded_mainloop_in_thread(pa_threaded_mainloop *m);
 301
 302 PA_C_DECL_END
 303
 304 #endif