prebuilt/linux-x86/toolchain/i686-linux-glibc2.7-4.4.3/sysroot/usr/include/pulse/thread-mainloop.h

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