[Lldb-commits] [lldb] r166800 - /lldb/trunk/include/lldb/Host/Predicate.h

[Andrew Kaylor]

Author: akaylor
Date: Fri Oct 26 14:28:36 2012
New Revision: 166800

URL: http://llvm.org/viewvc/llvm-project?rev=166800&view=rev
Log:
This patch updates comments in the Predicate class to describe a subtle behavior that callers may need to be aware.  It also adds documentation for one function which didn’t have any.

The subtle behavior is that the Predicate wait functions may not detect transitory changes in the predicate value.  Consider the following scenario.

Thread A waits for a bit to be set in the predicate value.
Thread B sets the bit in the predicate value.
Before Thread A wakes up, Thread C clears the bit in the predicate value.
Thread A wakes, checks the value and goes back to waiting.

The mutex and condition variables protect access to the value, but they offer no guarantee that another thread will not acquire the mutex and change the value before a waiting thread is restarted after a change.

I believe that the current behavior is correct and reasonable.  I just want to leave a marker to prevent possible problems in the future or to help anyone who might be unfortunate enough to encounter such a problem.

Modified:
    lldb/trunk/include/lldb/Host/Predicate.h

Modified: lldb/trunk/include/lldb/Host/Predicate.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/Host/Predicate.h?rev=166800&r1=166799&r2=166800&view=diff
==============================================================================
--- lldb/trunk/include/lldb/Host/Predicate.h (original)
+++ lldb/trunk/include/lldb/Host/Predicate.h Fri Oct 26 14:28:36 2012
@@ -193,6 +193,13 @@
     /// 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.
     ///
@@ -236,6 +243,13 @@
     /// 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.
     ///
@@ -280,6 +294,13 @@
     /// 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.
     ///
@@ -320,6 +341,41 @@
         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)
     {
@@ -359,6 +415,13 @@
     /// 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.
     ///