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