1 module pulse.mainloop; 2 3 import core.stdc.config; 4 5 import pulse.mainloopapi; 6 7 extern (C): 8 9 /*** 10 This file is part of PulseAudio. 11 12 Copyright 2004-2006 Lennart Poettering 13 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB 14 15 PulseAudio is free software; you can redistribute it and/or modify 16 it under the terms of the GNU Lesser General Public License as published 17 by the Free Software Foundation; either version 2.1 of the License, 18 or (at your option) any later version. 19 20 PulseAudio is distributed in the hope that it will be useful, but 21 WITHOUT ANY WARRANTY; without even the implied warranty of 22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 23 General Public License for more details. 24 25 You should have received a copy of the GNU Lesser General Public License 26 along with PulseAudio; if not, see <http://www.gnu.org/licenses/>. 27 ***/ 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 struct pa_mainloop; 79 80 /** Allocate a new main loop object. Free with pa_mainloop_free. */ 81 pa_mainloop* pa_mainloop_new (); 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. The timeout is specified in microseconds. */ 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 (const(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 110 quit() routine is called. Returns a negative value on error. Optionally return 111 the return value as specified with the main loop's quit() routine in the integer 112 variable retval points to. */ 113 int pa_mainloop_run (pa_mainloop* m, int* retval); 114 115 /** Return the abstract main loop abstraction layer vtable for this 116 main loop. No need to free the API as it is owned by the loop 117 and is destroyed when the loop is freed. */ 118 pa_mainloop_api* pa_mainloop_get_api (pa_mainloop* m); 119 120 /** Shutdown the main loop with the specified return value */ 121 void pa_mainloop_quit (pa_mainloop* m, int retval); 122 123 /** Interrupt a running poll (for threaded systems) */ 124 void pa_mainloop_wakeup (pa_mainloop* m); 125 126 /** Generic prototype of a poll() like function */ 127 alias pa_poll_func = int function (pollfd* ufds, c_ulong nfds, int timeout, void* userdata); 128 129 /** Change the poll() implementation */ 130 void pa_mainloop_set_poll_func (pa_mainloop* m, pa_poll_func poll_func, void* userdata); 131