* 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

3 files changed, 42 insertions, 6 deletions

diff --git a/src/polyp/thread-mainloop.c b/src/polyp/thread-mainloop.c
index 51fafe92..62813acd 100644
--- a/src/polyp/thread-mainloop.c
+++ b/src/polyp/thread-mainloop.c
@@ -48,7 +48,8 @@ struct pa_threaded_mainloop {
     pa_mainloop *real_mainloop;
     pthread_t thread_id;
     pthread_mutex_t mutex;
-    pthread_cond_t cond;
+    int n_waiting;
+    pthread_cond_t cond, release_cond;
     int thread_running;
 };
 
@@ -98,11 +99,13 @@ pa_threaded_mainloop *pa_threaded_mainloop_new(void) {
 
     pthread_mutexattr_init(&a);
     pthread_mutexattr_settype(&a, PTHREAD_MUTEX_RECURSIVE);
-    pthread_mutex_init(&m->mutex, NULL);
+    pthread_mutex_init(&m->mutex, &a);
     pthread_mutexattr_destroy(&a);
     
     pthread_cond_init(&m->cond, NULL);
+    pthread_cond_init(&m->release_cond, NULL);
     m->thread_running = 0;
+    m->n_waiting = 0;
 
     return m;
 }
@@ -121,6 +124,7 @@ void pa_threaded_mainloop_free(pa_threaded_mainloop* m) {
 
     pthread_mutex_destroy(&m->mutex);
     pthread_cond_destroy(&m->cond);
+    pthread_cond_destroy(&m->release_cond);
     
     pa_xfree(m);
 }
@@ -181,10 +185,13 @@ void pa_threaded_mainloop_unlock(pa_threaded_mainloop *m) {
     pthread_mutex_unlock(&m->mutex);
 }
 
-void pa_threaded_mainloop_signal(pa_threaded_mainloop *m) {
+void pa_threaded_mainloop_signal(pa_threaded_mainloop *m, int wait_for_release) {
     assert(m);
     
     pthread_cond_broadcast(&m->cond);
+
+    if (wait_for_release && m->n_waiting > 0)
+        pthread_cond_wait(&m->release_cond, &m->mutex);
 }
 
 void pa_threaded_mainloop_wait(pa_threaded_mainloop *m) {
@@ -193,7 +200,11 @@ void pa_threaded_mainloop_wait(pa_threaded_mainloop *m) {
     /* Make sure that this function is not called from the helper thread */
     assert(!m->thread_running || !pthread_equal(pthread_self(), m->thread_id));
 
+    m->n_waiting ++;
     pthread_cond_wait(&m->cond, &m->mutex);
+    assert(m->n_waiting > 0);
+    m->n_waiting --;
+    pthread_cond_signal(&m->release_cond);
 }
 
 int pa_threaded_mainloop_get_retval(pa_threaded_mainloop *m) {
diff --git a/src/polyp/thread-mainloop.h b/src/polyp/thread-mainloop.h
index 8e53de58..d4762e27 100644
--- a/src/polyp/thread-mainloop.h
+++ b/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);
 
diff --git a/src/tests/thread-mainloop-test.c b/src/tests/thread-mainloop-test.c
index 8232c4a3..24e18b37 100644
--- a/src/tests/thread-mainloop-test.c
+++ b/src/tests/thread-mainloop-test.c
@@ -33,8 +33,9 @@
 #include <polyp/thread-mainloop.h>
 
 static void tcb(pa_mainloop_api*a, pa_time_event *e, const struct timeval *tv, void *userdata) {
-    fprintf(stderr, "TIME EVENT\n");
-    pa_threaded_mainloop_signal(userdata);
+    fprintf(stderr, "TIME EVENT START\n");
+    pa_threaded_mainloop_signal(userdata, 1);
+    fprintf(stderr, "TIME EVENT END\n");
 }
 
 int main(PA_GCC_UNUSED int argc, PA_GCC_UNUSED char *argv[]) {