* optionally, make pa_threaded_mainloop_signal() wait until the main thread took over control

* more header file comments


git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@831 fefdeb5f-60dc-0310-8127-8f9354f1896f

src/polyp/thread-mainloop.h

@@ -40,13 +40,37 @@ pa_threaded_mainloop *pa_threaded_mainloop_new(void);
 /** Free a main loop object */
 void pa_threaded_mainloop_free(pa_threaded_mainloop* m);
 
+/** Start the event loop thread. */
 int pa_threaded_mainloop_start(pa_threaded_mainloop *m);
+
+/** Terminate the event loop thread cleanly */
 void pa_threaded_mainloop_stop(pa_threaded_mainloop *m);
+
+/** Lock the event loop object, effectively blocking the event loop
+ * thread from processing events. You can use this to enforce
+ * exclusive access to all objects attached to the event loop. This
+ * function may not be called inside the event loop thread. */
 void pa_threaded_mainloop_lock(pa_threaded_mainloop *m);
+
+/** Unlock the event loop object, inverse of pa_threaded_mainloop_lock() */
 void pa_threaded_mainloop_unlock(pa_threaded_mainloop *m);
-void pa_threaded_mainloop_signal(pa_threaded_mainloop *m);
+
+/** Wait for an event to be signalled by the event loop thread. You
+ * can use this to pass data from the event loop thread to the main
+ * thread in synchronized fashion. This function may not be called
+ * inside the event loop thread. Prior to this call the event loop
+ * object needs to be locked using pa_threaded_mainloop_lock(). While
+ * waiting the lock will be released, immediately before returning it
+ * will be acquired again. */
 void pa_threaded_mainloop_wait(pa_threaded_mainloop *m);
 
+/** Signal all threads waiting for a signalling event in
+ * pa_threaded_mainloop_wait(). If wait_for_release is non-zero, do
+ * not return before the signal was accepted by a
+ * pa_threaded_mainloop_wait() call. While waiting for that condition
+ * the event loop object is unlocked. */
+void pa_threaded_mainloop_signal(pa_threaded_mainloop *m, int wait_for_release);
+
 /** Return the return value as specified with the main loop's quit() routine. */
 int pa_threaded_mainloop_get_retval(pa_threaded_mainloop *m);