Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit f1147f7d authored by Tom Cherry's avatar Tom Cherry
Browse files

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
parent 7a5d535c

libutils/include/utils/Condition.h

+7 −12
Original line number Original line Diff line number Diff line
@@ -41,6 +41,11 @@ namespace android { 
 * call wait(), then either re-wait() if things aren't quite what you want,

 * 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

 * or unlock the mutex and continue.  All threads calling wait() must

 * use the same mutex for a given Condition.

 * 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 {

class Condition {

public:

public:
@@ -58,10 +63,11 @@ public: 
    explicit Condition(int type);

    explicit Condition(int type);

    ~Condition();

    ~Condition();

    // Wait on the condition variable.  Lock the mutex before calling.

    // Wait on the condition variable.  Lock the mutex before calling.

    // Note that spurious wake-ups may happen.

    status_t wait(Mutex& mutex);

    status_t wait(Mutex& mutex);

    // same with relative timeout

    // same with relative timeout

    status_t waitRelative(Mutex& mutex, nsecs_t reltime);

    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();

    void signal();

    // Signal the condition variable, allowing one or all threads to continue.

    // Signal the condition variable, allowing one or all threads to continue.

    void signal(WakeUpType type) {

    void signal(WakeUpType type) {
@@ -142,17 +148,6 @@ inline status_t Condition::waitRelative(Mutex& mutex, nsecs_t reltime) { 
    return -pthread_cond_timedwait(&mCond, &mutex.mMutex, &ts);

    return -pthread_cond_timedwait(&mCond, &mutex.mMutex, &ts);

}

}

inline void Condition::signal() {

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);

    pthread_cond_signal(&mCond);

}

}

inline void Condition::broadcast() {

inline void Condition::broadcast() {