1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
#ifndef foomainloophfoo
#define foomainloophfoo
/* $Id$ */
/***
This file is part of polypaudio.
polypaudio is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version.
polypaudio is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with polypaudio; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA.
***/
#include <polyp/mainloop-api.h>
#include <polyp/cdecl.h>
PA_C_DECL_BEGIN
/** \page mainloop Mainloop
*
* \section overv_sec Overview
*
* The built-in main loop implementation is based on the poll() system call.
* It supports the functions defined in the main loop abstraction and very
* little else.
*
* The main loop is created using pa_mainloop_new() and destroyed using
* pa_mainloop_free(). To get access to the main loop abstraction,
* pa_mainloop_get_api() is used.
*
* \section iter_sec Iteration
*
* The main loop is designed around the concept of iterations. Each iteration
* consists of three steps that repeat during the application's entire
* lifetime:
*
* -# Prepare - Dispatch deferred events, build a list of file descriptors
* that need to be monitored and calculate the next timeout.
* -# Poll - Execute the actuall poll() system call.
* -# Dispatch - Dispatch any timeouts and file descriptors that have fired.
*
* When using the main loop, the application can either execute each
* iteration, one at a time, using pa_mainloop_iterate(), or let the library
* iterate automatically using pa_mainloop_run().
*
* \section thread_sec Threads
*
* The main loop functions are designed to be thread safe, but the objects
* are not. What this means is that multiple main loops can be used, but only
* one object per thread.
*
*/
/** \file
*
* A minimal main loop implementation based on the C library's poll()
* function. Using the routines defined herein you may create a simple
* main loop supporting the generic main loop abstraction layer as
* defined in \ref mainloop-api.h. This implementation is thread safe
* as long as you access the main loop object from a single thread only.*/
/** An opaque main loop object */
typedef struct pa_mainloop pa_mainloop;
/** Allocate a new main loop object */
pa_mainloop *pa_mainloop_new(void);
/** Free a main loop object */
void pa_mainloop_free(pa_mainloop* m);
/** Prepare for a single iteration of the main loop. Returns a negative value
on error or exit request. timeout specifies a maximum timeout for the subsequent
poll, or -1 for blocking behaviour. Defer events are also dispatched when this
function is called. On success returns the number of source dispatched in this
iteration.*/
int pa_mainloop_prepare(pa_mainloop *m, int timeout);
/** Execute the previously prepared poll. Returns a negative value on error.*/
int pa_mainloop_poll(pa_mainloop *m);
/** Dispatch timeout and io events from the previously executed poll. Returns
a negative value on error. On success returns the number of source dispatched. */
int pa_mainloop_dispatch(pa_mainloop *m);
/** Return the return value as specified with the main loop's quit() routine. */
int pa_mainloop_get_retval(pa_mainloop *m);
/** Run a single iteration of the main loop. This is a convenience function
for pa_mainloop_prepare(), pa_mainloop_poll() and pa_mainloop_dispatch().
Returns a negative value on error or exit request. If block is nonzero,
block for events if none are queued. Optionally return the return value as
specified with the main loop's quit() routine in the integer variable retval points
to. On success returns the number of source dispatched in this iteration. */
int pa_mainloop_iterate(pa_mainloop *m, int block, int *retval);
/** Run unlimited iterations of the main loop object until the main loop's quit() routine is called. */
int pa_mainloop_run(pa_mainloop *m, int *retval);
/** Return the abstract main loop abstraction layer vtable for this main loop. */
pa_mainloop_api* pa_mainloop_get_api(pa_mainloop*m);
/** Shutdown the main loop */
void pa_mainloop_quit(pa_mainloop *m, int r);
/** Interrupt a running poll (for threaded systems) */
void pa_mainloop_wakeup(pa_mainloop *m);
PA_C_DECL_END
#endif
|
