code.delx.au - pulseaudio/blob - src/pulse/mainloop.h

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