1 module pulse.threadmainloop; 2 3 import pulse.mainloopapi; 4 5 extern (C): 6 7 /*** 8 This file is part of PulseAudio. 9 10 Copyright 2006 Lennart Poettering 11 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB 12 13 PulseAudio is free software; you can redistribute it and/or modify 14 it under the terms of the GNU Lesser General Public License as published 15 by the Free Software Foundation; either version 2.1 of the License, 16 or (at your option) any later version. 17 18 PulseAudio is distributed in the hope that it will be useful, but 19 WITHOUT ANY WARRANTY; without even the implied warranty of 20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 General Public License for more details. 22 23 You should have received a copy of the GNU Lesser General Public License 24 along with PulseAudio; if not, see <http://www.gnu.org/licenses/>. 25 ***/ 26 27 /** \page threaded_mainloop Threaded Main Loop 28 * 29 * \section overv_sec Overview 30 * 31 * The threaded main loop implementation is a special version of the primary 32 * main loop implementation (see \ref mainloop). For the basic design, see 33 * its documentation. 34 * 35 * The added feature in the threaded main loop is that it spawns a new thread 36 * that runs the real main loop. This allows a synchronous application to use 37 * the asynchronous API without risking stalling the PulseAudio library. 38 * 39 * \section creat_sec Creation 40 * 41 * A pa_threaded_mainloop object is created using pa_threaded_mainloop_new(). 42 * This will only allocate the required structures though, so to use it the 43 * thread must also be started. This is done through 44 * pa_threaded_mainloop_start(), after which you can start using the main loop. 45 * 46 * \section destr_sec Destruction 47 * 48 * When the PulseAudio connection has been terminated, the thread must be 49 * stopped and the resources freed. Stopping the thread is done using 50 * pa_threaded_mainloop_stop(), which must be called without the lock (see 51 * below) held. When that function returns, the thread is stopped and the 52 * pa_threaded_mainloop object can be freed using pa_threaded_mainloop_free(). 53 * 54 * \section lock_sec Locking 55 * 56 * Since the PulseAudio API doesn't allow concurrent accesses to objects, 57 * a locking scheme must be used to guarantee safe usage. The threaded main 58 * loop API provides such a scheme through the functions 59 * pa_threaded_mainloop_lock() and pa_threaded_mainloop_unlock(). 60 * 61 * The lock is recursive, so it's safe to use it multiple times from the same 62 * thread. Just make sure you call pa_threaded_mainloop_unlock() the same 63 * number of times you called pa_threaded_mainloop_lock(). 64 * 65 * The lock needs to be held whenever you call any PulseAudio function that 66 * uses an object associated with this main loop. Those objects include 67 * pa_mainloop, pa_context, pa_stream and pa_operation, and the various event 68 * objects (pa_io_event, pa_time_event, pa_defer_event). Make sure you do not 69 * hold on to the lock more than necessary though, as the threaded main loop 70 * stops while the lock is held. 71 * 72 * Example: 73 * 74 * \code 75 * void my_check_stream_func(pa_threaded_mainloop *m, pa_stream *s) { 76 * pa_stream_state_t state; 77 * 78 * pa_threaded_mainloop_lock(m); 79 * 80 * state = pa_stream_get_state(s); 81 * 82 * pa_threaded_mainloop_unlock(m); 83 * 84 * if (state == PA_STREAM_READY) 85 * printf("Stream is ready!"); 86 * else 87 * printf("Stream is not ready!"); 88 * } 89 * \endcode 90 * 91 * \section cb_sec Callbacks 92 * 93 * Callbacks in PulseAudio are asynchronous, so they require extra care when 94 * using them together with a threaded main loop. 95 * 96 * The easiest way to turn the callback based operations into synchronous 97 * ones, is to simply wait for the callback to be called and continue from 98 * there. This is the approach chosen in PulseAudio's threaded API. 99 * 100 * \subsection basic_subsec Basic callbacks 101 * 102 * For the basic case, where all that is required is to wait for the callback 103 * to be invoked, the code should look something like this: 104 * 105 * Example: 106 * 107 * \code 108 * static void my_drain_callback(pa_stream *s, int success, void *userdata) { 109 * pa_threaded_mainloop *m; 110 * 111 * m = userdata; 112 * assert(m); 113 * 114 * pa_threaded_mainloop_signal(m, 0); 115 * } 116 * 117 * void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) { 118 * pa_operation *o; 119 * 120 * pa_threaded_mainloop_lock(m); 121 * 122 * o = pa_stream_drain(s, my_drain_callback, m); 123 * assert(o); 124 * 125 * while (pa_operation_get_state(o) == PA_OPERATION_RUNNING) 126 * pa_threaded_mainloop_wait(m); 127 * 128 * pa_operation_unref(o); 129 * 130 * pa_threaded_mainloop_unlock(m); 131 * } 132 * \endcode 133 * 134 * The main function, my_drain_stream_func(), will wait for the callback to 135 * be called using pa_threaded_mainloop_wait(). 136 * 137 * If your application is multi-threaded, then this waiting must be 138 * done inside a while loop. The reason for this is that multiple 139 * threads might be using pa_threaded_mainloop_wait() at the same 140 * time. Each thread must therefore verify that it was its callback 141 * that was invoked. Also the underlying OS synchronization primitives 142 * are usually not free of spurious wake-ups, so a 143 * pa_threaded_mainloop_wait() must be called within a loop even if 144 * you have only one thread waiting. 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, 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 signalled. 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 * volatile drain_result = NULL; 167 * 168 * static void my_drain_callback(pa_stream*s, int success, void *userdata) { 169 * pa_threaded_mainloop *m; 170 * 171 * m = 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 (drain_result == NULL) 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 value 1 passed 208 * to 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 wait. 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 threaded 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 their own mechanisms. 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 * See also \subpage threaded_mainloop 242 */ 243 244 /** An opaque threaded main loop object */ 245 struct 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. Free with pa_threaded_mainloop_free. */ 250 pa_threaded_mainloop* pa_threaded_mainloop_new (); 251 252 /** Free a threaded main loop object. If the event loop thread is 253 * still running, terminate it with pa_threaded_mainloop_stop() 254 * first. */ 255 void pa_threaded_mainloop_free (pa_threaded_mainloop* m); 256 257 /** Start the event loop thread. Returns zero on success, negative on error. */ 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 a 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 pa_threaded_mainloop_signal() being called. You need to 283 * make sure to handle 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_accept 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 300 * pa_mainloop_quit() routine. */ 301 int pa_threaded_mainloop_get_retval (const(pa_threaded_mainloop)* m); 302 303 /** Return the main loop abstraction layer vtable for this main loop. 304 * There is no need to free this object as it is owned by the loop 305 * and is destroyed when the loop is freed. */ 306 pa_mainloop_api* pa_threaded_mainloop_get_api (pa_threaded_mainloop* m); 307 308 /** Returns non-zero when called from within the event loop thread. \since 0.9.7 */ 309 int pa_threaded_mainloop_in_thread (pa_threaded_mainloop* m); 310 311 /** Sets the name of the thread. \since 5.0 */ 312 void pa_threaded_mainloop_set_name (pa_threaded_mainloop* m, const(char)* name); 313 314 /** Runs the given callback in the mainloop thread without the lock held. The 315 * caller is responsible for ensuring that PulseAudio data structures are only 316 * accessed in a thread-safe way (that is, APIs that take pa_context and 317 * pa_stream are not thread-safe, and should not accessed without some 318 * synchronisation). This is the only situation in which 319 * pa_threaded_mainloop_lock() and pa_threaded_mainloop_unlock() may be used 320 * in the mainloop thread context. \since 13.0 */ 321 void pa_threaded_mainloop_once_unlocked ( 322 pa_threaded_mainloop* m, 323 void function (pa_threaded_mainloop* m, void* userdata) callback, 324 void* userdata); 325