volume: use PA_VOLUME_MAX instead of (pa_volume_t) -1

[pulseaudio] / src / pulse / thread-mainloop.h

diff --git a/src/pulse/thread-mainloop.h b/src/pulse/thread-mainloop.h
index 521e29b01da32144a721a07627aee00d1a10322f..e847070dfae7f69b202a580717987538d64804d5 100644 (file)
--- a/src/pulse/thread-mainloop.h
+++ b/src/pulse/thread-mainloop.h
@@ -9,7 +9,7 @@
 
   PulseAudio is free software; you can redistribute it and/or modify
   it under the terms of the GNU Lesser General Public License as published
 
   PulseAudio is free software; you can redistribute it and/or modify
   it under the terms of the GNU Lesser General Public License as published

-  by the Free Software Foundation; either version 2 of the License,
+  by the Free Software Foundation; either version 2.1 of the License,

   or (at your option) any later version.
 
   PulseAudio is distributed in the hope that it will be useful, but
   or (at your option) any later version.
 
   PulseAudio is distributed in the hope that it will be useful, but


@@ -25,6 +25,7 @@
 
 #include <pulse/mainloop-api.h>
 #include <pulse/cdecl.h>
 
 #include <pulse/mainloop-api.h>
 #include <pulse/cdecl.h>

+#include <pulse/version.h>

 
 PA_C_DECL_BEGIN
 
 
 PA_C_DECL_BEGIN
 


@@ -107,10 +108,10 @@ PA_C_DECL_BEGIN
  * Example:
  *
  * \code
  * Example:
  *
  * \code

- * static void my_drain_callback(pa_stream*s, int success, void *userdata) {
+ * static void my_drain_callback(pa_stream *s, int success, void *userdata) {

  *     pa_threaded_mainloop *m;
  *
  *     pa_threaded_mainloop *m;
  *

- *     m = (pa_threaded_mainloop*)userdata;
+ *     m = userdata;

  *     assert(m);
  *
  *     pa_threaded_mainloop_signal(m, 0);
  *     assert(m);
  *
  *     pa_threaded_mainloop_signal(m, 0);


@@ -124,7 +125,7 @@ PA_C_DECL_BEGIN
  *     o = pa_stream_drain(s, my_drain_callback, m);
  *     assert(o);
  *
  *     o = pa_stream_drain(s, my_drain_callback, m);
  *     assert(o);
  *

- *     while (pa_operation_get_state(o) != OPERATION_DONE)
+ *     while (pa_operation_get_state(o) == PA_OPERATION_RUNNING)

  *         pa_threaded_mainloop_wait(m);
  *
  *     pa_operation_unref(o);
  *         pa_threaded_mainloop_wait(m);
  *
  *     pa_operation_unref(o);


@@ -136,15 +137,19 @@ PA_C_DECL_BEGIN
  * The main function, my_drain_stream_func(), will wait for the callback to
  * be called using pa_threaded_mainloop_wait().
  *
  * The main function, my_drain_stream_func(), will wait for the callback to
  * be called using pa_threaded_mainloop_wait().
  *

- * If your application is multi-threaded, then this waiting must be done
- * inside a while loop. The reason for this is that multiple threads might be
- * using pa_threaded_mainloop_wait() at the same time. Each thread must
- * therefore verify that it was its callback that was invoked.
+ * If your application is multi-threaded, then this waiting must be
+ * done inside a while loop. The reason for this is that multiple
+ * threads might be using pa_threaded_mainloop_wait() at the same
+ * time. Each thread must therefore verify that it was its callback
+ * that was invoked. Also the underlying OS synchronization primitives
+ * are usually not free of spurious wake-ups, so a
+ * pa_threaded_mainloop_wait() must be called within a loop even if
+ * you have only one thread waiting.

  *
  * The callback, my_drain_callback(), indicates to the main function that it
  * has been called using pa_threaded_mainloop_signal().
  *
  *
  * The callback, my_drain_callback(), indicates to the main function that it
  * has been called using pa_threaded_mainloop_signal().
  *

- * As you can see, both pa_threaded_mainloop_wait() may only be called with
+ * As you can see, pa_threaded_mainloop_wait() may only be called with

  * the lock held. The same thing is true for pa_threaded_mainloop_signal(),
  * but as the lock is held before the callback is invoked, you do not have to
  * deal with that.
  * the lock held. The same thing is true for pa_threaded_mainloop_signal(),
  * but as the lock is held before the callback is invoked, you do not have to
  * deal with that.


@@ -166,7 +171,7 @@ PA_C_DECL_BEGIN
  * static void my_drain_callback(pa_stream*s, int success, void *userdata) {
  *     pa_threaded_mainloop *m;
  *
  * static void my_drain_callback(pa_stream*s, int success, void *userdata) {
  *     pa_threaded_mainloop *m;
  *

- *     m = (pa_threaded_mainloop*)userdata;
+ *     m = userdata;

  *     assert(m);
  *
  *     drain_result = &success;
  *     assert(m);
  *
  *     drain_result = &success;


@@ -182,7 +187,7 @@ PA_C_DECL_BEGIN
  *     o = pa_stream_drain(s, my_drain_callback, m);
  *     assert(o);
  *
  *     o = pa_stream_drain(s, my_drain_callback, m);
  *     assert(o);
  *

- *     while (pa_operation_get_state(o) != OPERATION_DONE)
+ *     while (pa_operation_get_state(o) == PA_OPERATION_RUNNING)

  *         pa_threaded_mainloop_wait(m);
  *
  *     pa_operation_unref(o);
  *         pa_threaded_mainloop_wait(m);
  *
  *     pa_operation_unref(o);


@@ -273,7 +278,9 @@ void pa_threaded_mainloop_unlock(pa_threaded_mainloop *m);
  * 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
  * 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. */
+ * will be acquired again. This function may spuriously wake up even
+ * without _signal() being called. You need to make sure to handle
+ * that! */

 void pa_threaded_mainloop_wait(pa_threaded_mainloop *m);
 
 /** Signal all threads waiting for a signalling event in
 void pa_threaded_mainloop_wait(pa_threaded_mainloop *m);
 
 /** Signal all threads waiting for a signalling event in