code.delx.au - pulseaudio/blob - polyp/mainloop.h

   1 #ifndef foomainloophfoo
   2 #define foomainloophfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of polypaudio.
   8
   9   polypaudio 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   polypaudio 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 polypaudio; 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 "mainloop-api.h"
  26 #include "cdecl.h"
  27
  28 PA_C_DECL_BEGIN
  29
  30 /** \file
  31  *
  32  * A minimal main loop implementation based on the C library's poll()
  33  * function. Using the routines defined herein you may create a simple
  34  * main loop supporting the generic main loop abstraction layer as
  35  * defined in \ref mainloop-api.h. This implementation is thread safe
  36  * as long as you access the main loop object from a single thread only.*/
  37
  38 /** \pa_mainloop
  39  * An opaque main loop object
  40  */
  41 typedef struct pa_mainloop pa_mainloop;
  42
  43 /** Allocate a new main loop object */
  44 pa_mainloop *pa_mainloop_new(void);
  45
  46 /** Free a main loop object */
  47 void pa_mainloop_free(pa_mainloop* m);
  48
  49
  50 /** Prepare for a single iteration of the main loop. Returns a negative value
  51 on error or exit request. timeout specifies a maximum timeout for the subsequent
  52 poll, or -1 for blocking behaviour. Defer events are also dispatched when this
  53 function is called. On success returns the number of source dispatched in this
  54 iteration.*/
  55 int pa_mainloop_prepare(pa_mainloop *m, int timeout);
  56 /** Execute the previously prepared poll. Returns a negative value on error.*/
  57 int pa_mainloop_poll(pa_mainloop *m);
  58 /** Dispatch timeout and io events from the previously executed poll. Returns
  59 a negative value on error. On success returns the number of source dispatched. */
  60 int pa_mainloop_dispatch(pa_mainloop *m);
  61
  62 /** Return the return value as specified with the main loop's quit() routine. */
  63 int pa_mainloop_get_retval(pa_mainloop *m);
  64
  65 /** Run a single iteration of the main loop. This is a convenience function
  66 for pa_mainloop_prepare(), pa_mainloop_poll() and pa_mainloop_dispatch().
  67 Returns a negative value on error or exit request. If block is nonzero,
  68 block for events if none are queued. Optionally return the return value as
  69 specified with the main loop's quit() routine in the integer variable retval points
  70 to. On success returns the number of source dispatched in this iteration. */
  71 int pa_mainloop_iterate(pa_mainloop *m, int block, int *retval);
  72
  73 /** Run unlimited iterations of the main loop object until the main loop's quit() routine is called. */
  74 int pa_mainloop_run(pa_mainloop *m, int *retval);
  75
  76 /** Return the abstract main loop abstraction layer vtable for this main loop. This calls pa_mainloop_iterate() iteratively.*/
  77 pa_mainloop_api* pa_mainloop_get_api(pa_mainloop*m);
  78
  79 /** Return non-zero when there are any deferred events pending. \since 0.5 */
  80 int pa_mainloop_deferred_pending(pa_mainloop *m);
  81
  82 /** Shutdown the main loop */
  83 void pa_mainloop_quit(pa_mainloop *m, int r);
  84
  85 /** Interrupt a running poll (for threaded systems) */
  86 void pa_mainloop_wakeup(pa_mainloop *m);
  87
  88 PA_C_DECL_END
  89
  90 #endif