1 #ifndef foothreadmainloophfoo
2 #define foothreadmainloophfoo
7 This file is part of PulseAudio.
9 Copyright 2006 Lennart Poettering
10 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
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.
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.
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
28 #include <pulse/mainloop-api.h>
29 #include <pulse/cdecl.h>
33 /** \page threaded_mainloop Threaded Main Loop
35 * \section overv_sec Overview
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
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.
45 * \section creat_sec Creation
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.
52 * \section destr_sec Destruction
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().
60 * \section lock_sec Locking
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().
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().
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.
79 * void my_check_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
80 * pa_stream_state_t state;
82 * pa_threaded_mainloop_lock(m);
84 * state = pa_stream_get_state(s);
86 * pa_threaded_mainloop_unlock(m);
88 * if (state == PA_STREAM_READY)
89 * printf("Stream is ready!");
91 * printf("Stream is not ready!");
95 * \section cb_sec Callbacks
97 * Callbacks in PulseAudio are asynchronous, so they require extra care when
98 * using them together with a threaded main loop.
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.
104 * \subsection basic_subsec Basic callbacks
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:
112 * static void my_drain_callback(pa_stream*s, int success, void *userdata) {
113 * pa_threaded_mainloop *m;
115 * m = (pa_threaded_mainloop*)userdata;
118 * pa_threaded_mainloop_signal(m, 0);
121 * void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
124 * pa_threaded_mainloop_lock(m);
126 * o = pa_stream_drain(s, my_drain_callback, m);
129 * while (pa_operation_get_state(o) != OPERATION_DONE)
130 * pa_threaded_mainloop_wait(m);
132 * pa_operation_unref(o);
134 * pa_threaded_mainloop_unlock(m);
138 * The main function, my_drain_stream_func(), will wait for the callback to
139 * be called using pa_threaded_mainloop_wait().
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.
146 * The callback, my_drain_callback(), indicates to the main function that it
147 * has been called using pa_threaded_mainloop_signal().
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
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.
159 * \subsection data_subsec Data callbacks
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:
166 * static int *drain_result;
168 * static void my_drain_callback(pa_stream*s, int success, void *userdata) {
169 * pa_threaded_mainloop *m;
171 * m = (pa_threaded_mainloop*)userdata;
174 * drain_result = &success;
176 * pa_threaded_mainloop_signal(m, 1);
179 * void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
182 * pa_threaded_mainloop_lock(m);
184 * o = pa_stream_drain(s, my_drain_callback, m);
187 * while (pa_operation_get_state(o) != OPERATION_DONE)
188 * pa_threaded_mainloop_wait(m);
190 * pa_operation_unref(o);
193 * printf("Success!");
195 * printf("Bitter defeat...");
197 * pa_threaded_mainloop_accept(m);
199 * pa_threaded_mainloop_unlock(m);
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
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
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().
220 * \subsection async_subsec Asynchronous callbacks
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.
228 * The callbacks that are completely asynchronous are:
230 * \li State callbacks for contexts, streams, etc.
231 * \li Subscription notifications
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. */
241 /** An opaque threaded main loop object */
242 typedef struct pa_threaded_mainloop pa_threaded_mainloop
;
244 /** Allocate a new threaded main loop object. You have to call
245 * pa_threaded_mainloop_start() before the event loop thread starts
247 pa_threaded_mainloop
*pa_threaded_mainloop_new(void);
249 /** Free a threaded main loop object. If the event loop thread is
250 * still running, it is terminated using pa_threaded_mainloop_stop()
252 void pa_threaded_mainloop_free(pa_threaded_mainloop
* m
);
254 /** Start the event loop thread. */
255 int pa_threaded_mainloop_start(pa_threaded_mainloop
*m
);
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
);
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
);
269 /** Unlock the event loop object, inverse of pa_threaded_mainloop_lock() */
270 void pa_threaded_mainloop_unlock(pa_threaded_mainloop
*m
);
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
);
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
);
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
);
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
);
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
);
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
);