432 lines
16 KiB
C++
432 lines
16 KiB
C++
/**
|
|
* @file llcond.h
|
|
* @author Nat Goodspeed
|
|
* @date 2019-07-10
|
|
* @brief LLCond is a wrapper around condition_variable to encapsulate the
|
|
* obligatory condition_variable usage pattern. We also provide
|
|
* simplified versions LLScalarCond, LLBoolCond and LLOneShotCond.
|
|
*
|
|
* $LicenseInfo:firstyear=2019&license=viewerlgpl$
|
|
* Copyright (c) 2019, Linden Research, Inc.
|
|
* $/LicenseInfo$
|
|
*/
|
|
|
|
#if ! defined(LL_LLCOND_H)
|
|
#define LL_LLCOND_H
|
|
|
|
#include "llunits.h"
|
|
#include "llcoros.h"
|
|
#include LLCOROS_MUTEX_HEADER
|
|
#include "mutex.h"
|
|
#include <chrono>
|
|
|
|
/**
|
|
* LLCond encapsulates the pattern required to use a condition_variable. It
|
|
* bundles subject data, a mutex and a condition_variable: the three required
|
|
* data objects. It provides wait() methods analogous to condition_variable,
|
|
* but using the contained condition_variable and the contained mutex. It
|
|
* provides modify() methods accepting an invocable to safely modify the
|
|
* contained data and notify waiters. These methods implicitly perform the
|
|
* required locking.
|
|
*
|
|
* The generic LLCond template assumes that DATA might be a struct or class.
|
|
* For a scalar DATA type, consider LLScalarCond instead. For specifically
|
|
* bool, consider LLBoolCond.
|
|
*
|
|
* Use of LLCoros::ConditionVariable makes LLCond work between
|
|
* coroutines as well as between threads.
|
|
*/
|
|
template <typename DATA>
|
|
class LLCond
|
|
{
|
|
public:
|
|
typedef DATA value_type;
|
|
|
|
private:
|
|
// This is the DATA controlled by the condition_variable.
|
|
value_type mData;
|
|
// condition_variable must be used in conjunction with a mutex. Use
|
|
// LLCoros::Mutex instead of std::mutex because the latter blocks
|
|
// the entire calling thread, whereas the former blocks only the current
|
|
// coroutine within the calling thread. Yet LLCoros::Mutex is safe to
|
|
// use across threads as well: it subsumes std::mutex functionality.
|
|
LLCoros::Mutex mMutex;
|
|
// Use LLCoros::ConditionVariable for the same reason.
|
|
LLCoros::ConditionVariable mCond;
|
|
using LockType = LLCoros::LockType;
|
|
using cv_status = LLCoros::cv_status;
|
|
|
|
public:
|
|
/// LLCond can be explicitly initialized with a specific value for mData if
|
|
/// desired.
|
|
LLCond(const value_type& init=value_type()):
|
|
mData(init)
|
|
{}
|
|
|
|
/// LLCond is move-only
|
|
LLCond(const LLCond&) = delete;
|
|
LLCond& operator=(const LLCond&) = delete;
|
|
|
|
/**
|
|
* get() returns the stored DATA by value -- so to use get(), DATA must
|
|
* be copyable. The only way to get a non-const reference -- to modify
|
|
* the stored DATA -- is via update_one() or update_all().
|
|
*/
|
|
value_type get()
|
|
{
|
|
LockType lk(mMutex);
|
|
return mData;
|
|
}
|
|
|
|
/**
|
|
* get(functor) returns whatever the functor returns. It allows us to peek
|
|
* at the stored DATA without copying the whole thing. The functor must
|
|
* accept a const reference to DATA. If you want to modify DATA, call
|
|
* update_one() or update_all() instead.
|
|
*/
|
|
template <typename FUNC>
|
|
auto get(FUNC&& func)
|
|
{
|
|
LockType lk(mMutex);
|
|
return std::forward<FUNC>(func)(const_data());
|
|
}
|
|
|
|
/**
|
|
* Pass update_one() an invocable accepting non-const (DATA&). The
|
|
* invocable will presumably modify the referenced DATA. update_one()
|
|
* will lock the mutex, call the invocable and then call notify_one() on
|
|
* the condition_variable.
|
|
*
|
|
* For scalar DATA, it's simpler to use LLScalarCond::set_one(). Use
|
|
* update_one() when DATA is a struct or class.
|
|
*/
|
|
template <typename MODIFY>
|
|
void update_one(MODIFY&& modify)
|
|
{
|
|
{ // scope of lock can/should end before notify_one()
|
|
LockType lk(mMutex);
|
|
std::forward<MODIFY>(modify)(mData);
|
|
}
|
|
mCond.notify_one();
|
|
}
|
|
|
|
/**
|
|
* Pass update_all() an invocable accepting non-const (DATA&). The
|
|
* invocable will presumably modify the referenced DATA. update_all()
|
|
* will lock the mutex, call the invocable and then call notify_all() on
|
|
* the condition_variable.
|
|
*
|
|
* For scalar DATA, it's simpler to use LLScalarCond::set_all(). Use
|
|
* update_all() when DATA is a struct or class.
|
|
*/
|
|
template <typename MODIFY>
|
|
void update_all(MODIFY&& modify)
|
|
{
|
|
{ // scope of lock can/should end before notify_all()
|
|
LockType lk(mMutex);
|
|
std::forward<MODIFY>(modify)(mData);
|
|
}
|
|
mCond.notify_all();
|
|
}
|
|
|
|
/**
|
|
* Pass wait() a predicate accepting (const DATA&), returning bool. The
|
|
* predicate returns true when the condition for which it is waiting has
|
|
* been satisfied, presumably determined by examining the referenced DATA.
|
|
* wait() locks the mutex and, until the predicate returns true, calls
|
|
* wait() on the condition_variable.
|
|
*/
|
|
template <typename Pred>
|
|
void wait(Pred&& pred)
|
|
{
|
|
LockType lk(mMutex);
|
|
// We must iterate explicitly since the predicate accepted by
|
|
// condition_variable::wait() requires a different signature:
|
|
// condition_variable::wait() calls its predicate with no arguments.
|
|
// Fortunately, the loop is straightforward.
|
|
// We advise the caller to pass a predicate accepting (const DATA&).
|
|
// But what if they instead pass a predicate accepting non-const
|
|
// (DATA&)? Such a predicate could modify mData, which would be Bad.
|
|
// Forbid that.
|
|
while (! std::forward<Pred>(pred)(const_data()))
|
|
{
|
|
mCond.wait(lk);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Pass wait_for() a chrono::duration, indicating how long we're willing
|
|
* to wait, and a predicate accepting (const DATA&), returning bool. The
|
|
* predicate returns true when the condition for which it is waiting has
|
|
* been satisfied, presumably determined by examining the referenced DATA.
|
|
* wait_for() locks the mutex and, until the predicate returns true, calls
|
|
* wait_for() on the condition_variable. wait_for() returns false if
|
|
* condition_variable::wait_for() timed out without the predicate
|
|
* returning true.
|
|
*/
|
|
template <typename Rep, typename Period, typename Pred>
|
|
bool wait_for(const std::chrono::duration<Rep, Period>& timeout_duration, Pred&& pred)
|
|
{
|
|
// Instead of replicating wait_until() logic, convert duration to
|
|
// time_point and just call wait_until().
|
|
// An implementation in which we repeatedly called
|
|
// condition_variable::wait_for() with our passed duration would be
|
|
// wrong! We'd keep pushing the timeout time farther and farther into
|
|
// the future. This way, we establish a definite timeout time and
|
|
// stick to it.
|
|
return wait_until(std::chrono::steady_clock::now() + timeout_duration,
|
|
std::forward<Pred>(pred));
|
|
}
|
|
|
|
/**
|
|
* This wait_for() overload accepts F32Milliseconds as the duration. Any
|
|
* duration unit defined in llunits.h is implicitly convertible to
|
|
* F32Milliseconds. The semantics of this method are the same as the
|
|
* generic wait_for() method.
|
|
*/
|
|
template <typename Pred>
|
|
bool wait_for(F32Milliseconds timeout_duration, Pred&& pred)
|
|
{
|
|
return wait_for(convert(timeout_duration), std::forward<Pred>(pred));
|
|
}
|
|
|
|
protected:
|
|
// convert F32Milliseconds to a chrono::duration
|
|
auto convert(F32Milliseconds duration)
|
|
{
|
|
// std::chrono::milliseconds doesn't like to be constructed from a
|
|
// float (F32), rubbing our nose in the thought that
|
|
// std::chrono::duration::rep is probably integral. Therefore
|
|
// converting F32Milliseconds to std::chrono::milliseconds would lose
|
|
// precision. Use std::chrono::microseconds instead. Extract the F32
|
|
// milliseconds from F32Milliseconds, scale to microseconds, construct
|
|
// std::chrono::microseconds from that value.
|
|
return std::chrono::microseconds{ std::chrono::microseconds::rep(duration.value() * 1000) };
|
|
}
|
|
|
|
private:
|
|
// It's important to pass a const ref to certain user-specified functors
|
|
// that aren't supposed to be able to modify mData.
|
|
const value_type& const_data() const { return mData; }
|
|
|
|
/**
|
|
* Pass wait_until() a chrono::time_point, indicating the time at which we
|
|
* should stop waiting, and a predicate accepting (const DATA&), returning
|
|
* bool. The predicate returns true when the condition for which it is
|
|
* waiting has been satisfied, presumably determined by examining the
|
|
* referenced DATA. wait_until() locks the mutex and, until the predicate
|
|
* returns true, calls wait_until() on the condition_variable.
|
|
* wait_until() returns false if condition_variable::wait_until() timed
|
|
* out without the predicate returning true.
|
|
*
|
|
* Originally this class and its subclasses published wait_until() methods
|
|
* corresponding to each wait_for() method. But that raised all sorts of
|
|
* fascinating questions about the time zone of the passed time_point:
|
|
* local time? server time? UTC? The bottom line is that for LLCond
|
|
* timeout purposes, we really shouldn't have to care -- timeout duration
|
|
* is all we need. This private method remains because it's the simplest
|
|
* way to support iteratively waiting across spurious wakeups while
|
|
* honoring a fixed timeout.
|
|
*/
|
|
template <typename Clock, typename Duration, typename Pred>
|
|
bool wait_until(const std::chrono::time_point<Clock, Duration>& timeout_time, Pred&& pred)
|
|
{
|
|
LockType lk(mMutex);
|
|
// We advise the caller to pass a predicate accepting (const DATA&).
|
|
// But what if they instead pass a predicate accepting non-const
|
|
// (DATA&)? Such a predicate could modify mData, which would be Bad.
|
|
// Forbid that.
|
|
while (! std::forward<Pred>(pred)(const_data()))
|
|
{
|
|
if (cv_status::timeout == mCond.wait_until(lk, timeout_time))
|
|
{
|
|
// It's possible that wait_until() timed out AND the predicate
|
|
// became true more or less simultaneously. Even though
|
|
// wait_until() timed out, check the predicate one more time.
|
|
return std::forward<Pred>(pred)(const_data());
|
|
}
|
|
}
|
|
return true;
|
|
}
|
|
};
|
|
|
|
template <typename DATA>
|
|
class LLScalarCond: public LLCond<DATA>
|
|
{
|
|
using super = LLCond<DATA>;
|
|
|
|
public:
|
|
using typename super::value_type;
|
|
using super::get;
|
|
using super::wait;
|
|
using super::wait_for;
|
|
|
|
/// LLScalarCond can be explicitly initialized with a specific value for
|
|
/// mData if desired.
|
|
LLScalarCond(const value_type& init=value_type()):
|
|
super(init)
|
|
{}
|
|
|
|
/// Pass set_one() a new value to which to update mData. set_one() will
|
|
/// lock the mutex, update mData and then call notify_one() on the
|
|
/// condition_variable.
|
|
void set_one(const value_type& value)
|
|
{
|
|
super::update_one([&value](value_type& data){ data = value; });
|
|
}
|
|
|
|
/// Pass set_all() a new value to which to update mData. set_all() will
|
|
/// lock the mutex, update mData and then call notify_all() on the
|
|
/// condition_variable.
|
|
void set_all(const value_type& value)
|
|
{
|
|
super::update_all([&value](value_type& data){ data = value; });
|
|
}
|
|
|
|
/**
|
|
* Pass wait_equal() a value for which to wait. wait_equal() locks the
|
|
* mutex and, until the stored DATA equals that value, calls wait() on the
|
|
* condition_variable.
|
|
*/
|
|
void wait_equal(const value_type& value)
|
|
{
|
|
super::wait([&value](const value_type& data){ return (data == value); });
|
|
}
|
|
|
|
/**
|
|
* Pass wait_for_equal() a chrono::duration, indicating how long we're
|
|
* willing to wait, and a value for which to wait. wait_for_equal() locks
|
|
* the mutex and, until the stored DATA equals that value, calls
|
|
* wait_for() on the condition_variable. wait_for_equal() returns false if
|
|
* condition_variable::wait_for() timed out without the stored DATA being
|
|
* equal to the passed value.
|
|
*/
|
|
template <typename Rep, typename Period>
|
|
bool wait_for_equal(const std::chrono::duration<Rep, Period>& timeout_duration,
|
|
const value_type& value)
|
|
{
|
|
return super::wait_for(timeout_duration,
|
|
[&value](const value_type& data){ return (data == value); });
|
|
}
|
|
|
|
/**
|
|
* This wait_for_equal() overload accepts F32Milliseconds as the duration.
|
|
* Any duration unit defined in llunits.h is implicitly convertible to
|
|
* F32Milliseconds. The semantics of this method are the same as the
|
|
* generic wait_for_equal() method.
|
|
*/
|
|
bool wait_for_equal(F32Milliseconds timeout_duration, const value_type& value)
|
|
{
|
|
return wait_for_equal(super::convert(timeout_duration), value);
|
|
}
|
|
|
|
/**
|
|
* Pass wait_unequal() a value from which to move away. wait_unequal()
|
|
* locks the mutex and, until the stored DATA no longer equals that value,
|
|
* calls wait() on the condition_variable.
|
|
*/
|
|
void wait_unequal(const value_type& value)
|
|
{
|
|
super::wait([&value](const value_type& data){ return (data != value); });
|
|
}
|
|
|
|
/**
|
|
* Pass wait_for_unequal() a chrono::duration, indicating how long we're
|
|
* willing to wait, and a value from which to move away.
|
|
* wait_for_unequal() locks the mutex and, until the stored DATA no longer
|
|
* equals that value, calls wait_for() on the condition_variable.
|
|
* wait_for_unequal() returns false if condition_variable::wait_for()
|
|
* timed out with the stored DATA still being equal to the passed value.
|
|
*/
|
|
template <typename Rep, typename Period>
|
|
bool wait_for_unequal(const std::chrono::duration<Rep, Period>& timeout_duration,
|
|
const value_type& value)
|
|
{
|
|
return super::wait_for(timeout_duration,
|
|
[&value](const value_type& data){ return (data != value); });
|
|
}
|
|
|
|
/**
|
|
* This wait_for_unequal() overload accepts F32Milliseconds as the duration.
|
|
* Any duration unit defined in llunits.h is implicitly convertible to
|
|
* F32Milliseconds. The semantics of this method are the same as the
|
|
* generic wait_for_unequal() method.
|
|
*/
|
|
bool wait_for_unequal(F32Milliseconds timeout_duration, const value_type& value)
|
|
{
|
|
return wait_for_unequal(super::convert(timeout_duration), value);
|
|
}
|
|
|
|
protected:
|
|
using super::convert;
|
|
};
|
|
|
|
/// Using bool as LLScalarCond's DATA seems like a particularly useful case
|
|
using LLBoolCond = LLScalarCond<bool>;
|
|
|
|
/// LLOneShotCond -- init false, set (and wait for) true
|
|
class LLOneShotCond: public LLBoolCond
|
|
{
|
|
using super = LLBoolCond;
|
|
|
|
public:
|
|
using typename super::value_type;
|
|
using super::get;
|
|
using super::wait;
|
|
using super::wait_for;
|
|
using super::wait_equal;
|
|
using super::wait_for_equal;
|
|
using super::wait_unequal;
|
|
using super::wait_for_unequal;
|
|
|
|
/// The bool stored in LLOneShotCond is initially false
|
|
LLOneShotCond(): super(false) {}
|
|
|
|
/// LLOneShotCond assumes that nullary set_one() means to set its bool true
|
|
void set_one(bool value=true)
|
|
{
|
|
super::set_one(value);
|
|
}
|
|
|
|
/// LLOneShotCond assumes that nullary set_all() means to set its bool true
|
|
void set_all(bool value=true)
|
|
{
|
|
super::set_all(value);
|
|
}
|
|
|
|
/**
|
|
* wait() locks the mutex and, until the stored bool is true, calls wait()
|
|
* on the condition_variable.
|
|
*/
|
|
void wait()
|
|
{
|
|
super::wait_unequal(false);
|
|
}
|
|
|
|
/**
|
|
* Pass wait_for() a chrono::duration, indicating how long we're willing
|
|
* to wait. wait_for() locks the mutex and, until the stored bool is true,
|
|
* calls wait_for() on the condition_variable. wait_for() returns false if
|
|
* condition_variable::wait_for() timed out without the stored bool being
|
|
* true.
|
|
*/
|
|
template <typename Rep, typename Period>
|
|
bool wait_for(const std::chrono::duration<Rep, Period>& timeout_duration)
|
|
{
|
|
return super::wait_for_unequal(timeout_duration, false);
|
|
}
|
|
|
|
/**
|
|
* This wait_for() overload accepts F32Milliseconds as the duration.
|
|
* Any duration unit defined in llunits.h is implicitly convertible to
|
|
* F32Milliseconds. The semantics of this method are the same as the
|
|
* generic wait_for() method.
|
|
*/
|
|
bool wait_for(F32Milliseconds timeout_duration)
|
|
{
|
|
return wait_for(super::convert(timeout_duration));
|
|
}
|
|
};
|
|
|
|
#endif /* ! defined(LL_LLCOND_H) */
|