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

source code of include/pulse/thread-mainloop.h