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