Clarify that Condition::wait() can spuriously wake up
Also, remove the clarification that Condition::signal() wakes exactly
one thread as in the presence of spurious wake ups, this clarification
does not provide a safe guarantee to developers.
Bug: 34592766
Test: Build
Change-Id: I34df02e44a70a18fe04ceda858d002ef129c1fd9
diff --git a/libutils/include/utils/Condition.h b/libutils/include/utils/Condition.h
index 2c80acd..3019a21 100644
--- a/libutils/include/utils/Condition.h
+++ b/libutils/include/utils/Condition.h
@@ -41,6 +41,11 @@
* call wait(), then either re-wait() if things aren't quite what you want,
* or unlock the mutex and continue. All threads calling wait() must
* use the same mutex for a given Condition.
+ *
+ * On Android and Apple platforms, these are implemented as a simple wrapper
+ * around pthread condition variables. Care must be taken to abide by
+ * the pthreads semantics, in particular, a boolean predicate must
+ * be re-evaluated after a wake-up, as spurious wake-ups may happen.
*/
class Condition {
public:
@@ -58,10 +63,11 @@
explicit Condition(int type);
~Condition();
// Wait on the condition variable. Lock the mutex before calling.
+ // Note that spurious wake-ups may happen.
status_t wait(Mutex& mutex);
// same with relative timeout
status_t waitRelative(Mutex& mutex, nsecs_t reltime);
- // Signal the condition variable, allowing exactly one thread to continue.
+ // Signal the condition variable, allowing one thread to continue.
void signal();
// Signal the condition variable, allowing one or all threads to continue.
void signal(WakeUpType type) {
@@ -142,17 +148,6 @@
return -pthread_cond_timedwait(&mCond, &mutex.mMutex, &ts);
}
inline void Condition::signal() {
- /*
- * POSIX says pthread_cond_signal wakes up "one or more" waiting threads.
- * However bionic follows the glibc guarantee which wakes up "exactly one"
- * waiting thread.
- *
- * man 3 pthread_cond_signal
- * pthread_cond_signal restarts one of the threads that are waiting on
- * the condition variable cond. If no threads are waiting on cond,
- * nothing happens. If several threads are waiting on cond, exactly one
- * is restarted, but it is not specified which.
- */
pthread_cond_signal(&mCond);
}
inline void Condition::broadcast() {