← Back to branch summary

~binli/ubuntu/vivid/pulseaudio/load-extcon-module

« back to all changes in this revision

Viewing changes to src/pulse/mainloop.h

  • Committer: Bin Li
  • Date: 2016-01-23 15:04:48 UTC
  • Revision ID: bin.li@canonical.com-20160123150448-5ockvw4p5xxntda4
init the 1:6.0-0ubuntu9.15 from silo 12

Show diffs side-by-side

added added

removed removed

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