lldb/Host/Predicate.h

//===-- Predicate.h ---------------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_Predicate_h_
#define liblldb_Predicate_h_
#if defined(__cplusplus)

#include "lldb/Host/Mutex.h"
#include "lldb/Host/Condition.h"
#include <stdint.h>
#include <time.h>

//#define DB_PTHREAD_LOG_EVENTS

//----------------------------------------------------------------------
/// Enumerations for broadcasting.
//----------------------------------------------------------------------
namespace lldb_private {

typedef enum
{
    eBroadcastNever,    ///< No broadcast will be sent when the value is modified.
    eBroadcastAlways,   ///< Always send a broadcast when the value is modified.
    eBroadcastOnChange  ///< Only broadcast if the value changes when the value is modified.

} PredicateBroadcastType;

//----------------------------------------------------------------------
/// @class Predicate Predicate.h "lldb/Host/Predicate.h"
/// @brief A C++ wrapper class for providing threaded access to a value
/// of type T.
///
/// A templatized class that provides multi-threaded access to a value
/// of type T. Threads can efficiently wait for bits within T to be set
/// or reset, or wait for T to be set to be equal/not equal to a
/// specified values.
//----------------------------------------------------------------------
template <class T>
class Predicate
{
public:

    //------------------------------------------------------------------
    /// Default constructor.
    ///
    /// Initializes the mutex, condition and value with their default
    /// constructors.
    //------------------------------------------------------------------
    Predicate () :
        m_value(),
        m_mutex(),
        m_condition()
    {
    }

    //------------------------------------------------------------------
    /// Construct with initial T value \a initial_value.
    ///
    /// Initializes the mutex and condition with their default
    /// constructors, and initializes the value with \a initial_value.
    ///
    /// @param[in] initial_value
    ///     The initial value for our T object.
    //------------------------------------------------------------------
    Predicate (T initial_value)  :
        m_value(initial_value),
        m_mutex(),
        m_condition()
    {
    }

    //------------------------------------------------------------------
    /// Destructor.
    ///
    /// Destrory the condition, mutex, and T objects.
    //------------------------------------------------------------------
    ~Predicate ()
    {
    }


    //------------------------------------------------------------------
    /// Value get accessor.
    ///
    /// Copies the current \a m_value in a thread safe manor and returns
    /// the copied value.
    ///
    /// @return
    ///     A copy of the current value.
    //------------------------------------------------------------------
    T
    GetValue () const
    {
        Mutex::Locker locker(m_mutex);
        T value = m_value;
        return value;
    }

    //------------------------------------------------------------------
    /// Value set accessor.
    ///
    /// Set the contained \a m_value to \a new_value in a thread safe
    /// way and broadcast if needed.
    ///
    /// @param[in] value
    ///     The new value to set.
    ///
    /// @param[in] broadcast_type
    ///     A value indicating when and if to broadast. See the
    ///     PredicateBroadcastType enumeration for details.
    ///
    /// @see Predicate::Broadcast()
    //------------------------------------------------------------------
    void
    SetValue (T value, PredicateBroadcastType broadcast_type)
    {
        Mutex::Locker locker(m_mutex);
#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (value = 0x%8.8x, broadcast_type = %i)\n", __FUNCTION__, value, broadcast_type);
#endif
        const T old_value = m_value;
        m_value = value;

        Broadcast(old_value, broadcast_type);
    }

    //------------------------------------------------------------------
    /// Set some bits in \a m_value.
    ///
    /// Logically set the bits \a bits in the contained \a m_value in a
    /// thread safe way and broadcast if needed.
    ///
    /// @param[in] bits
    ///     The bits to set in \a m_value.
    ///
    /// @param[in] broadcast_type
    ///     A value indicating when and if to broadast. See the
    ///     PredicateBroadcastType enumeration for details.
    ///
    /// @see Predicate::Broadcast()
    //------------------------------------------------------------------
    void
    SetValueBits (T bits, PredicateBroadcastType broadcast_type)
    {
        Mutex::Locker locker(m_mutex);
#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (bits = 0x%8.8x, broadcast_type = %i)\n", __FUNCTION__, bits, broadcast_type);
#endif
        const T old_value = m_value;
        m_value |= bits;

        Broadcast(old_value, broadcast_type);
    }

    //------------------------------------------------------------------
    /// Reset some bits in \a m_value.
    ///
    /// Logically reset (clear) the bits \a bits in the contained
    /// \a m_value in a thread safe way and broadcast if needed.
    ///
    /// @param[in] bits
    ///     The bits to clear in \a m_value.
    ///
    /// @param[in] broadcast_type
    ///     A value indicating when and if to broadast. See the
    ///     PredicateBroadcastType enumeration for details.
    ///
    /// @see Predicate::Broadcast()
    //------------------------------------------------------------------
    void
    ResetValueBits (T bits, PredicateBroadcastType broadcast_type)
    {
        Mutex::Locker locker(m_mutex);
#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (bits = 0x%8.8x, broadcast_type = %i)\n", __FUNCTION__, bits, broadcast_type);
#endif
        const T old_value = m_value;
        m_value &= ~bits;

        Broadcast(old_value, broadcast_type);
    }

    //------------------------------------------------------------------
    /// Wait for bits to be set in \a m_value.
    ///
    /// Waits in a thread safe way for any bits in \a bits to get
    /// logically set in \a m_value. If any bits are already set in
    /// \a m_value, this function will return without waiting.
    ///
    /// It is possible for the value to be changed between the time
    /// the bits are set and the time the waiting thread wakes up.
    /// If the bits are no longer set when the waiting thread wakes
    /// up, it will go back into a wait state.  It may be necessary
    /// for the calling code to use additional thread synchronization
    /// methods to detect transitory states.
    ///
    /// @param[in] bits
    ///     The bits we are waiting to be set in \a m_value.
    ///
    /// @param[in] abstime
    ///     If non-NULL, the absolute time at which we should stop
    ///     waiting, else wait an infinite amount of time.
    ///
    /// @return
    ///     Any bits of the requested bits that actually were set within
    ///     the time specified. Zero if a timeout or unrecoverable error
    ///     occurred.
    //------------------------------------------------------------------
    T
    WaitForSetValueBits (T bits, const TimeValue *abstime = NULL)
    {
        int err = 0;
        // pthread_cond_timedwait() or pthread_cond_wait() will atomically
        // unlock the mutex and wait for the condition to be set. When either
        // function returns, they will re-lock the mutex. We use an auto lock/unlock
        // class (Mutex::Locker) to allow us to return at any point in this
        // function and not have to worry about unlocking the mutex.
        Mutex::Locker locker(m_mutex);
#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (bits = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, bits, abstime, m_value);
#endif
        while (err == 0 && ((m_value & bits) == 0))
        {
            err = m_condition.Wait (m_mutex, abstime);
        }
#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (bits = 0x%8.8x), m_value = 0x%8.8x, returning 0x%8.8x\n", __FUNCTION__, bits, m_value, m_value & bits);
#endif

        return m_value & bits;
    }

    //------------------------------------------------------------------
    /// Wait for bits to be reset in \a m_value.
    ///
    /// Waits in a thread safe way for any bits in \a bits to get
    /// logically reset in \a m_value. If all bits are already reset in
    /// \a m_value, this function will return without waiting.
    ///
    /// It is possible for the value to be changed between the time
    /// the bits are reset and the time the waiting thread wakes up.
    /// If the bits are no set when the waiting thread wakes up, it will
    /// go back into a wait state.  It may be necessary for the calling
    /// code to use additional thread synchronization methods to detect
    /// transitory states.
    ///
    /// @param[in] bits
    ///     The bits we are waiting to be reset in \a m_value.
    ///
    /// @param[in] abstime
    ///     If non-NULL, the absolute time at which we should stop
    ///     waiting, else wait an infinite amount of time.
    ///
    /// @return
    ///     Zero on successful waits, or non-zero if a timeout or
    ///     unrecoverable error occurs.
    //------------------------------------------------------------------
    T
    WaitForResetValueBits (T bits, const TimeValue *abstime = NULL)
    {
        int err = 0;

        // pthread_cond_timedwait() or pthread_cond_wait() will atomically
        // unlock the mutex and wait for the condition to be set. When either
        // function returns, they will re-lock the mutex. We use an auto lock/unlock
        // class (Mutex::Locker) to allow us to return at any point in this
        // function and not have to worry about unlocking the mutex.
        Mutex::Locker locker(m_mutex);

#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (bits = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, bits, abstime, m_value);
#endif
        while (err == 0 && ((m_value & bits) != 0))
        {
            err = m_condition.Wait (m_mutex, abstime);
        }

#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (bits = 0x%8.8x), m_value = 0x%8.8x, returning 0x%8.8x\n", __FUNCTION__, bits, m_value, m_value & bits);
#endif
        return m_value & bits;
    }

    //------------------------------------------------------------------
    /// Wait for \a m_value to be equal to \a value.
    ///
    /// Waits in a thread safe way for \a m_value to be equal to \a
    /// value. If \a m_value is already equal to \a value, this
    /// function will return without waiting.
    ///
    /// It is possible for the value to be changed between the time
    /// the value is set and the time the waiting thread wakes up.
    /// If the value no longer matches the requested value when the
    /// waiting thread wakes up, it will go back into a wait state.  It
    /// may be necessary for the calling code to use additional thread
    /// synchronization methods to detect transitory states.
    ///
    /// @param[in] value
    ///     The value we want \a m_value to be equal to.
    ///
    /// @param[in] abstime
    ///     If non-NULL, the absolute time at which we should stop
    ///     waiting, else wait an infinite amount of time.
    ///
    /// @param[out] timed_out
    ///     If not null, set to true if we return because of a time out,
    ///     and false if the value was set.
    ///
    /// @return
    ///     @li \b true if the \a m_value is equal to \a value
    ///     @li \b false otherwise
    //------------------------------------------------------------------
    bool
    WaitForValueEqualTo (T value, const TimeValue *abstime = NULL, bool *timed_out = NULL)
    {
        int err = 0;
        // pthread_cond_timedwait() or pthread_cond_wait() will atomically
        // unlock the mutex and wait for the condition to be set. When either
        // function returns, they will re-lock the mutex. We use an auto lock/unlock
        // class (Mutex::Locker) to allow us to return at any point in this
        // function and not have to worry about unlocking the mutex.
        Mutex::Locker locker(m_mutex);

#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (value = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, value, abstime, m_value);
#endif
        if (timed_out)
            *timed_out = false;

        while (err == 0 && m_value != value)
        {
            err = m_condition.Wait (m_mutex, abstime, timed_out);
        }

        return m_value == value;
    }

    //------------------------------------------------------------------
    /// Wait for \a m_value to be equal to \a value and then set it to
    /// a new value.
    ///
    /// Waits in a thread safe way for \a m_value to be equal to \a
    /// value and then sets \a m_value to \a new_value. If \a m_value
    /// is already equal to \a value, this function will immediately
    /// set \a m_value to \a new_value and return without waiting.
    ///
    /// It is possible for the value to be changed between the time
    /// the value is set and the time the waiting thread wakes up.
    /// If the value no longer matches the requested value when the
    /// waiting thread wakes up, it will go back into a wait state.  It
    /// may be necessary for the calling code to use additional thread
    /// synchronization methods to detect transitory states.
    ///
    /// @param[in] value
    ///     The value we want \a m_value to be equal to.
    ///
    /// @param[in] new_value
    ///     The value to which \a m_value will be set if \b true is
    ///     returned.
    ///
    /// @param[in] abstime
    ///     If non-NULL, the absolute time at which we should stop
    ///     waiting, else wait an infinite amount of time.
    ///
    /// @param[out] timed_out
    ///     If not null, set to true if we return because of a time out,
    ///     and false if the value was set.
    ///
    /// @return
    ///     @li \b true if the \a m_value became equal to \a value
    ///     @li \b false otherwise
    //------------------------------------------------------------------
    bool
    WaitForValueEqualToAndSetValueTo (T wait_value, T new_value, const TimeValue *abstime = NULL, bool *timed_out = NULL)
    {
        int err = 0;
        // pthread_cond_timedwait() or pthread_cond_wait() will atomically
        // unlock the mutex and wait for the condition to be set. When either
        // function returns, they will re-lock the mutex. We use an auto lock/unlock
        // class (Mutex::Locker) to allow us to return at any point in this
        // function and not have to worry about unlocking the mutex.
        Mutex::Locker locker(m_mutex);

#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (wait_value = 0x%8.8x, new_value = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, wait_value, new_value, abstime, m_value);
#endif
        if (timed_out)
            *timed_out = false;

        while (err == 0 && m_value != wait_value)
        {
            err = m_condition.Wait (m_mutex, abstime, timed_out);
        }

        if (m_value == wait_value)
        {
            m_value = new_value;
            return true;
        }

        return false;
    }


    //------------------------------------------------------------------
    /// Wait for \a m_value to not be equal to \a value.
    ///
    /// Waits in a thread safe way for \a m_value to not be equal to \a
    /// value. If \a m_value is already not equal to \a value, this
    /// function will return without waiting.
    ///
    /// It is possible for the value to be changed between the time
    /// the value is set and the time the waiting thread wakes up.
    /// If the value is equal to the test value when the waiting thread
    /// wakes up, it will go back into a wait state.  It may be
    /// necessary for the calling code to use additional thread
    /// synchronization methods to detect transitory states.
    ///
    /// @param[in] value
    ///     The value we want \a m_value to not be equal to.
    ///
    /// @param[out] new_value
    ///     The new value if \b true is returned.
    ///
    /// @param[in] abstime
    ///     If non-NULL, the absolute time at which we should stop
    ///     waiting, else wait an infinite amount of time.
    ///
    /// @return
    ///     @li \b true if the \a m_value is equal to \a value
    ///     @li \b false otherwise
    //------------------------------------------------------------------
    bool
    WaitForValueNotEqualTo (T value, T &new_value, const TimeValue *abstime = NULL)
    {
        int err = 0;
        // pthread_cond_timedwait() or pthread_cond_wait() will atomically
        // unlock the mutex and wait for the condition to be set. When either
        // function returns, they will re-lock the mutex. We use an auto lock/unlock
        // class (Mutex::Locker) to allow us to return at any point in this
        // function and not have to worry about unlocking the mutex.
        Mutex::Locker locker(m_mutex);
#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (value = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, value, abstime, m_value);
#endif
        while (err == 0 && m_value == value)
        {
            err = m_condition.Wait (m_mutex, abstime);
        }

        if (m_value != value)
        {
            new_value = m_value;
            return true;
        }
        return false;
    }

protected:
    //----------------------------------------------------------------------
    // pthread condition and mutex variable to controll access and allow
    // blocking between the main thread and the spotlight index thread.
    //----------------------------------------------------------------------
    T           m_value;        ///< The templatized value T that we are protecting access to
    mutable Mutex m_mutex;      ///< The mutex to use when accessing the data
    Condition   m_condition;    ///< The pthread condition variable to use for signaling that data available or changed.

private:

    //------------------------------------------------------------------
    /// Broadcast if needed.
    ///
    /// Check to see if we need to broadcast to our condition variable
    /// depedning on the \a old_value and on the \a broadcast_type.
    ///
    /// If \a broadcast_type is eBroadcastNever, no broadcast will be
    /// sent.
    ///
    /// If \a broadcast_type is eBroadcastAlways, the condition variable
    /// will always be broadcast.
    ///
    /// If \a broadcast_type is eBroadcastOnChange, the condition
    /// variable be broadcast if the owned value changes.
    //------------------------------------------------------------------
    void
    Broadcast (T old_value, PredicateBroadcastType broadcast_type)
    {
        bool broadcast = (broadcast_type == eBroadcastAlways) || ((broadcast_type == eBroadcastOnChange) && old_value != m_value);
#ifdef DB_PTHREAD_LOG_EVENTS
        printf("%s (old_value = 0x%8.8x, broadcast_type = %i) m_value = 0x%8.8x, broadcast = %u\n", __FUNCTION__, old_value, broadcast_type, m_value, broadcast);
#endif
        if (broadcast)
            m_condition.Broadcast();
    }


    DISALLOW_COPY_AND_ASSIGN(Predicate);
};

} // namespace lldb_private

#endif  // #if defined(__cplusplus)
#endif // #ifndef liblldb_Predicate_h_