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 (at) 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 306
