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 | |
29 | PA_C_DECL_BEGIN |
30 | |
31 | struct 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 */ |
80 | typedef struct pa_mainloop pa_mainloop; |
81 | |
82 | /** Allocate a new main loop object */ |
83 | pa_mainloop *pa_mainloop_new(void); |
84 | |
85 | /** Free a main loop object */ |
86 | void pa_mainloop_free(pa_mainloop* m); |
87 | |
88 | /** Prepare for a single iteration of the main loop. Returns a negative value |
89 | on error or exit request. timeout specifies a maximum timeout for the subsequent |
90 | poll, or -1 for blocking behaviour. .*/ |
91 | int pa_mainloop_prepare(pa_mainloop *m, int timeout); |
92 | |
93 | /** Execute the previously prepared poll. Returns a negative value on error.*/ |
94 | int pa_mainloop_poll(pa_mainloop *m); |
95 | |
96 | /** Dispatch timeout, io and deferred events from the previously executed poll. Returns |
97 | a negative value on error. On success returns the number of source dispatched. */ |
98 | int pa_mainloop_dispatch(pa_mainloop *m); |
99 | |
100 | /** Return the return value as specified with the main loop's quit() routine. */ |
101 | int pa_mainloop_get_retval(pa_mainloop *m); |
102 | |
103 | /** Run a single iteration of the main loop. This is a convenience function |
104 | for pa_mainloop_prepare(), pa_mainloop_poll() and pa_mainloop_dispatch(). |
105 | Returns a negative value on error or exit request. If block is nonzero, |
106 | block for events if none are queued. Optionally return the return value as |
107 | specified with the main loop's quit() routine in the integer variable retval points |
108 | to. On success returns the number of sources dispatched in this iteration. */ |
109 | int 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. */ |
112 | int 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. */ |
117 | pa_mainloop_api* pa_mainloop_get_api(pa_mainloop*m); |
118 | |
119 | /** Shutdown the main loop */ |
120 | void pa_mainloop_quit(pa_mainloop *m, int r); |
121 | |
122 | /** Interrupt a running poll (for threaded systems) */ |
123 | void pa_mainloop_wakeup(pa_mainloop *m); |
124 | |
125 | /** Generic prototype of a poll() like function */ |
126 | typedef int (*pa_poll_func)(struct pollfd *ufds, unsigned long nfds, int timeout, void*userdata); |
127 | |
128 | /** Change the poll() implementation */ |
129 | void pa_mainloop_set_poll_func(pa_mainloop *m, pa_poll_func poll_func, void *userdata); |
130 | |
131 | PA_C_DECL_END |
132 | |
133 | #endif |
134 | |