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

   1 #ifndef foothreadmainloophfoo
   2 #define foothreadmainloophfoo
   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 <polyp/mainloop-api.h>
  26 #include <polyp/cdecl.h>
  27
  28 PA_C_DECL_BEGIN
  29
  30 /** \file
  31  *
  32  * A thread based event loop implementation based on pa_mainloop. The
  33  * event loop is run in a helper thread in the background. A few
  34  * synchronization primitives are available to access the objects
  35  * attached to the event loop safely. */
  36
  37 /** An opaque threaded main loop object */
  38 typedef struct pa_threaded_mainloop pa_threaded_mainloop;
  39
  40 /** Allocate a new threaded main loop object. You have to call
  41  * pa_threaded_mainloop_start() before the event loop thread starts
  42  * running. */
  43 pa_threaded_mainloop *pa_threaded_mainloop_new(void);
  44
  45 /** Free a threaded main loop object. If the event loop thread is
  46  * still running, it is terminated using pa_threaded_mainloop_stop()
  47  * first. */
  48 void pa_threaded_mainloop_free(pa_threaded_mainloop* m);
  49
  50 /** Start the event loop thread. */
  51 int pa_threaded_mainloop_start(pa_threaded_mainloop *m);
  52
  53 /** Terminate the event loop thread cleanly. Make sure to unlock the
  54  * mainloop object before calling this function. */
  55 void pa_threaded_mainloop_stop(pa_threaded_mainloop *m);
  56
  57 /** Lock the event loop object, effectively blocking the event loop
  58  * thread from processing events. You can use this to enforce
  59  * exclusive access to all objects attached to the event loop. This
  60  * lock is recursive. This function may not be called inside the event
  61  * loop thread. Events that are dispatched from the event loop thread
  62  * are executed with this lock held. */
  63 void pa_threaded_mainloop_lock(pa_threaded_mainloop *m);
  64
  65 /** Unlock the event loop object, inverse of pa_threaded_mainloop_lock() */
  66 void pa_threaded_mainloop_unlock(pa_threaded_mainloop *m);
  67
  68 /** Wait for an event to be signalled by the event loop thread. You
  69  * can use this to pass data from the event loop thread to the main
  70  * thread in synchronized fashion. This function may not be called
  71  * inside the event loop thread. Prior to this call the event loop
  72  * object needs to be locked using pa_threaded_mainloop_lock(). While
  73  * waiting the lock will be released, immediately before returning it
  74  * will be acquired again. */
  75 void pa_threaded_mainloop_wait(pa_threaded_mainloop *m);
  76
  77 /** Signal all threads waiting for a signalling event in
  78  * pa_threaded_mainloop_wait(). If wait_for_release is non-zero, do
  79  * not return before the signal was accepted by a
  80  * pa_threaded_mainloop_accept() call. While waiting for that condition
  81  * the event loop object is unlocked. */
  82 void pa_threaded_mainloop_signal(pa_threaded_mainloop *m, int wait_for_accept);
  83
  84 /** Accept a signal from the event thread issued with
  85  * pa_threaded_mainloop_signal(). This call should only be used in
  86  * conjunction with pa_threaded_mainloop_signal() with a non-zero
  87  * wait_for_accept value.  */
  88 void pa_threaded_mainloop_accept(pa_threaded_mainloop *m);
  89
  90 /** Return the return value as specified with the main loop's quit() routine. */
  91 int pa_threaded_mainloop_get_retval(pa_threaded_mainloop *m);
  92
  93 /** Return the abstract main loop abstraction layer vtable for this main loop. */
  94 pa_mainloop_api* pa_threaded_mainloop_get_api(pa_threaded_mainloop*m);
  95
  96 PA_C_DECL_END
  97
  98 #endif