1#ifndef foomainloophfoo
2#define foomainloophfoo
3
4/***
5 This file is part of PulseAudio.
6
7 Copyright 2004-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, write to the Free Software
22 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
23 USA.
24***/
25
26#include <pulse/mainloop-api.h>
27#include <pulse/cdecl.h>
28
29PA_C_DECL_BEGIN
30
31struct pollfd;
32
33/** \page mainloop Main Loop
34 *
35 * \section overv_sec Overview
36 *
37 * The built-in main loop implementation is based on the poll() system call.
38 * It supports the functions defined in the main loop abstraction and very
39 * little else.
40 *
41 * The main loop is created using pa_mainloop_new() and destroyed using
42 * pa_mainloop_free(). To get access to the main loop abstraction,
43 * pa_mainloop_get_api() is used.
44 *
45 * \section iter_sec Iteration
46 *
47 * The main loop is designed around the concept of iterations. Each iteration
48 * consists of three steps that repeat during the application's entire
49 * lifetime:
50 *
51 * -# Prepare - Build a list of file descriptors
52 * that need to be monitored and calculate the next timeout.
53 * -# Poll - Execute the actual poll() system call.
54 * -# Dispatch - Dispatch any events that have fired.
55 *
56 * When using the main loop, the application can either execute each
57 * iteration, one at a time, using pa_mainloop_iterate(), or let the library
58 * iterate automatically using pa_mainloop_run().
59 *
60 * \section thread_sec Threads
61 *
62 * The main loop functions are designed to be thread safe, but the objects
63 * are not. What this means is that multiple main loops can be used, but only
64 * one object per thread.
65 *
66 */
67
68/** \file
69 *
70 * A minimal main loop implementation based on the C library's poll()
71 * function. Using the routines defined herein you may create a simple
72 * main loop supporting the generic main loop abstraction layer as
73 * defined in \ref mainloop-api.h. This implementation is thread safe
74 * as long as you access the main loop object from a single thread only.
75 *
76 * See also \subpage mainloop
77 */
78
79/** An opaque main loop object */
80typedef struct pa_mainloop pa_mainloop;
81
82/** Allocate a new main loop object */
83pa_mainloop *pa_mainloop_new(void);
84
85/** Free a main loop object */
86void pa_mainloop_free(pa_mainloop* m);
87
88/** Prepare for a single iteration of the main loop. Returns a negative value
89on error or exit request. timeout specifies a maximum timeout for the subsequent
90poll, or -1 for blocking behaviour. .*/
91int pa_mainloop_prepare(pa_mainloop *m, int timeout);
92
93/** Execute the previously prepared poll. Returns a negative value on error.*/
94int pa_mainloop_poll(pa_mainloop *m);
95
96/** Dispatch timeout, io and deferred events from the previously executed poll. Returns
97a negative value on error. On success returns the number of source dispatched. */
98int pa_mainloop_dispatch(pa_mainloop *m);
99
100/** Return the return value as specified with the main loop's quit() routine. */
101int pa_mainloop_get_retval(pa_mainloop *m);
102
103/** Run a single iteration of the main loop. This is a convenience function
104for pa_mainloop_prepare(), pa_mainloop_poll() and pa_mainloop_dispatch().
105Returns a negative value on error or exit request. If block is nonzero,
106block for events if none are queued. Optionally return the return value as
107specified with the main loop's quit() routine in the integer variable retval points
108to. On success returns the number of sources dispatched in this iteration. */
109int pa_mainloop_iterate(pa_mainloop *m, int block, int *retval);
110
111/** Run unlimited iterations of the main loop object until the main loop's quit() routine is called. */
112int pa_mainloop_run(pa_mainloop *m, int *retval);
113
114/** Return the abstract main loop abstraction layer vtable for this
115 main loop. No need to free the API as it is owned by the loop
116 and is destroyed when the loop is freed. */
117pa_mainloop_api* pa_mainloop_get_api(pa_mainloop*m);
118
119/** Shutdown the main loop */
120void pa_mainloop_quit(pa_mainloop *m, int r);
121
122/** Interrupt a running poll (for threaded systems) */
123void pa_mainloop_wakeup(pa_mainloop *m);
124
125/** Generic prototype of a poll() like function */
126typedef int (*pa_poll_func)(struct pollfd *ufds, unsigned long nfds, int timeout, void*userdata);
127
128/** Change the poll() implementation */
129void pa_mainloop_set_poll_func(pa_mainloop *m, pa_poll_func poll_func, void *userdata);
130
131PA_C_DECL_END
132
133#endif
134