class Condition

-----------------------------------------------------------------------------

Condition

-----------------------------------------------------------------------------

`Mutex` contains a number of member functions which take a `Condition` as an

argument; clients can wait for conditions to become `true` before attempting

to acquire the mutex. These sections are known as "condition critical"

sections. To use a `Condition`, you simply need to construct it, and use

within an appropriate `Mutex` member function; everything else in the

`Condition` class is an implementation detail.

A `Condition` is specified as a function pointer which returns a boolean.

`Condition` functions should be pure functions -- their results should depend

only on passed arguments, should not consult any external state (such as

clocks), and should have no side-effects, aside from debug logging. Any

objects that the function may access should be limited to those which are

constant while the mutex is blocked on the condition (e.g. a stack variable),

or objects of state protected explicitly by the mutex.

No matter which construction is used for `Condition`, the underlying

function pointer / functor / callable must not throw any

exceptions. Correctness of `Mutex` / `Condition` is not guaranteed in

the face of a throwing `Condition`. (When Abseil is allowed to depend

on C++17, these function pointers will be explicitly marked

`noexcept`; until then this requirement cannot be enforced in the

type system.)

Note: to use a `Condition`, you need only construct it and pass it to a

suitable `Mutex' member function, such as `Mutex::Await()`, or to the

constructor of one of the scope guard classes.

Example using LockWhen/Unlock:

// assume count_ is not internal reference count

int count_ ABSL_GUARDED_BY(mu_);

Condition count_is_zero(+[](int *count) { return *count == 0; },

&count

_);

mu_.LockWhen(count_is_zero);

// ...

mu_.Unlock();

Example using a scope guard:

{

MutexLock lock(

&mu

_, count_is_zero);

// ...

}

When multiple threads are waiting on exactly the same condition, make sure

that they are constructed with the same parameters (same pointer to function

+ arg, or same pointer to object + method), so that the mutex implementation

can avoid redundantly evaluating the same condition for each thread.