1 //===-- Predicate.h ---------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Predicate_h_
11 #define liblldb_Predicate_h_
12 #if defined(__cplusplus)
14 #include "lldb/lldb-defines.h"
15 #include "lldb/Host/Mutex.h"
16 #include "lldb/Host/Condition.h"
20 //#define DB_PTHREAD_LOG_EVENTS
22 //----------------------------------------------------------------------
23 /// Enumerations for broadcasting.
24 //----------------------------------------------------------------------
25 namespace lldb_private {
29 eBroadcastNever, ///< No broadcast will be sent when the value is modified.
30 eBroadcastAlways, ///< Always send a broadcast when the value is modified.
31 eBroadcastOnChange ///< Only broadcast if the value changes when the value is modified.
33 } PredicateBroadcastType;
35 //----------------------------------------------------------------------
36 /// @class Predicate Predicate.h "lldb/Host/Predicate.h"
37 /// @brief A C++ wrapper class for providing threaded access to a value
40 /// A templatized class that provides multi-threaded access to a value
41 /// of type T. Threads can efficiently wait for bits within T to be set
42 /// or reset, or wait for T to be set to be equal/not equal to a
44 //----------------------------------------------------------------------
50 //------------------------------------------------------------------
51 /// Default constructor.
53 /// Initializes the mutex, condition and value with their default
55 //------------------------------------------------------------------
63 //------------------------------------------------------------------
64 /// Construct with initial T value \a initial_value.
66 /// Initializes the mutex and condition with their default
67 /// constructors, and initializes the value with \a initial_value.
69 /// @param[in] initial_value
70 /// The initial value for our T object.
71 //------------------------------------------------------------------
72 Predicate (T initial_value) :
73 m_value(initial_value),
79 //------------------------------------------------------------------
82 /// Destroy the condition, mutex, and T objects.
83 //------------------------------------------------------------------
89 //------------------------------------------------------------------
90 /// Value get accessor.
92 /// Copies the current \a m_value in a thread safe manor and returns
96 /// A copy of the current value.
97 //------------------------------------------------------------------
101 Mutex::Locker locker(m_mutex);
106 //------------------------------------------------------------------
107 /// Value set accessor.
109 /// Set the contained \a m_value to \a new_value in a thread safe
110 /// way and broadcast if needed.
113 /// The new value to set.
115 /// @param[in] broadcast_type
116 /// A value indicating when and if to broadcast. See the
117 /// PredicateBroadcastType enumeration for details.
119 /// @see Predicate::Broadcast()
120 //------------------------------------------------------------------
122 SetValue (T value, PredicateBroadcastType broadcast_type)
124 Mutex::Locker locker(m_mutex);
125 #ifdef DB_PTHREAD_LOG_EVENTS
126 printf("%s (value = 0x%8.8x, broadcast_type = %i)\n", __FUNCTION__, value, broadcast_type);
128 const T old_value = m_value;
131 Broadcast(old_value, broadcast_type);
134 //------------------------------------------------------------------
135 /// Set some bits in \a m_value.
137 /// Logically set the bits \a bits in the contained \a m_value in a
138 /// thread safe way and broadcast if needed.
141 /// The bits to set in \a m_value.
143 /// @param[in] broadcast_type
144 /// A value indicating when and if to broadcast. See the
145 /// PredicateBroadcastType enumeration for details.
147 /// @see Predicate::Broadcast()
148 //------------------------------------------------------------------
150 SetValueBits (T bits, PredicateBroadcastType broadcast_type)
152 Mutex::Locker locker(m_mutex);
153 #ifdef DB_PTHREAD_LOG_EVENTS
154 printf("%s (bits = 0x%8.8x, broadcast_type = %i)\n", __FUNCTION__, bits, broadcast_type);
156 const T old_value = m_value;
159 Broadcast(old_value, broadcast_type);
162 //------------------------------------------------------------------
163 /// Reset some bits in \a m_value.
165 /// Logically reset (clear) the bits \a bits in the contained
166 /// \a m_value in a thread safe way and broadcast if needed.
169 /// The bits to clear in \a m_value.
171 /// @param[in] broadcast_type
172 /// A value indicating when and if to broadcast. See the
173 /// PredicateBroadcastType enumeration for details.
175 /// @see Predicate::Broadcast()
176 //------------------------------------------------------------------
178 ResetValueBits (T bits, PredicateBroadcastType broadcast_type)
180 Mutex::Locker locker(m_mutex);
181 #ifdef DB_PTHREAD_LOG_EVENTS
182 printf("%s (bits = 0x%8.8x, broadcast_type = %i)\n", __FUNCTION__, bits, broadcast_type);
184 const T old_value = m_value;
187 Broadcast(old_value, broadcast_type);
190 //------------------------------------------------------------------
191 /// Wait for bits to be set in \a m_value.
193 /// Waits in a thread safe way for any bits in \a bits to get
194 /// logically set in \a m_value. If any bits are already set in
195 /// \a m_value, this function will return without waiting.
197 /// It is possible for the value to be changed between the time
198 /// the bits are set and the time the waiting thread wakes up.
199 /// If the bits are no longer set when the waiting thread wakes
200 /// up, it will go back into a wait state. It may be necessary
201 /// for the calling code to use additional thread synchronization
202 /// methods to detect transitory states.
205 /// The bits we are waiting to be set in \a m_value.
207 /// @param[in] abstime
208 /// If non-NULL, the absolute time at which we should stop
209 /// waiting, else wait an infinite amount of time.
212 /// Any bits of the requested bits that actually were set within
213 /// the time specified. Zero if a timeout or unrecoverable error
215 //------------------------------------------------------------------
217 WaitForSetValueBits (T bits, const TimeValue *abstime = NULL)
220 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
221 // unlock the mutex and wait for the condition to be set. When either
222 // function returns, they will re-lock the mutex. We use an auto lock/unlock
223 // class (Mutex::Locker) to allow us to return at any point in this
224 // function and not have to worry about unlocking the mutex.
225 Mutex::Locker locker(m_mutex);
226 #ifdef DB_PTHREAD_LOG_EVENTS
227 printf("%s (bits = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, bits, abstime, m_value);
229 while (err == 0 && ((m_value & bits) == 0))
231 err = m_condition.Wait (m_mutex, abstime);
233 #ifdef DB_PTHREAD_LOG_EVENTS
234 printf("%s (bits = 0x%8.8x), m_value = 0x%8.8x, returning 0x%8.8x\n", __FUNCTION__, bits, m_value, m_value & bits);
237 return m_value & bits;
240 //------------------------------------------------------------------
241 /// Wait for bits to be reset in \a m_value.
243 /// Waits in a thread safe way for any bits in \a bits to get
244 /// logically reset in \a m_value. If all bits are already reset in
245 /// \a m_value, this function will return without waiting.
247 /// It is possible for the value to be changed between the time
248 /// the bits are reset and the time the waiting thread wakes up.
249 /// If the bits are no set when the waiting thread wakes up, it will
250 /// go back into a wait state. It may be necessary for the calling
251 /// code to use additional thread synchronization methods to detect
252 /// transitory states.
255 /// The bits we are waiting to be reset in \a m_value.
257 /// @param[in] abstime
258 /// If non-NULL, the absolute time at which we should stop
259 /// waiting, else wait an infinite amount of time.
262 /// Zero on successful waits, or non-zero if a timeout or
263 /// unrecoverable error occurs.
264 //------------------------------------------------------------------
266 WaitForResetValueBits (T bits, const TimeValue *abstime = NULL)
270 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
271 // unlock the mutex and wait for the condition to be set. When either
272 // function returns, they will re-lock the mutex. We use an auto lock/unlock
273 // class (Mutex::Locker) to allow us to return at any point in this
274 // function and not have to worry about unlocking the mutex.
275 Mutex::Locker locker(m_mutex);
277 #ifdef DB_PTHREAD_LOG_EVENTS
278 printf("%s (bits = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, bits, abstime, m_value);
280 while (err == 0 && ((m_value & bits) != 0))
282 err = m_condition.Wait (m_mutex, abstime);
285 #ifdef DB_PTHREAD_LOG_EVENTS
286 printf("%s (bits = 0x%8.8x), m_value = 0x%8.8x, returning 0x%8.8x\n", __FUNCTION__, bits, m_value, m_value & bits);
288 return m_value & bits;
291 //------------------------------------------------------------------
292 /// Wait for \a m_value to be equal to \a value.
294 /// Waits in a thread safe way for \a m_value to be equal to \a
295 /// value. If \a m_value is already equal to \a value, this
296 /// function will return without waiting.
298 /// It is possible for the value to be changed between the time
299 /// the value is set and the time the waiting thread wakes up.
300 /// If the value no longer matches the requested value when the
301 /// waiting thread wakes up, it will go back into a wait state. It
302 /// may be necessary for the calling code to use additional thread
303 /// synchronization methods to detect transitory states.
306 /// The value we want \a m_value to be equal to.
308 /// @param[in] abstime
309 /// If non-NULL, the absolute time at which we should stop
310 /// waiting, else wait an infinite amount of time.
312 /// @param[out] timed_out
313 /// If not null, set to true if we return because of a time out,
314 /// and false if the value was set.
317 /// @li \b true if the \a m_value is equal to \a value
318 /// @li \b false otherwise
319 //------------------------------------------------------------------
321 WaitForValueEqualTo (T value, const TimeValue *abstime = NULL, bool *timed_out = NULL)
324 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
325 // unlock the mutex and wait for the condition to be set. When either
326 // function returns, they will re-lock the mutex. We use an auto lock/unlock
327 // class (Mutex::Locker) to allow us to return at any point in this
328 // function and not have to worry about unlocking the mutex.
329 Mutex::Locker locker(m_mutex);
331 #ifdef DB_PTHREAD_LOG_EVENTS
332 printf("%s (value = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, value, abstime, m_value);
337 while (err == 0 && m_value != value)
339 err = m_condition.Wait (m_mutex, abstime, timed_out);
342 return m_value == value;
345 //------------------------------------------------------------------
346 /// Wait for \a m_value to be equal to \a value and then set it to
349 /// Waits in a thread safe way for \a m_value to be equal to \a
350 /// value and then sets \a m_value to \a new_value. If \a m_value
351 /// is already equal to \a value, this function will immediately
352 /// set \a m_value to \a new_value and return without waiting.
354 /// It is possible for the value to be changed between the time
355 /// the value is set and the time the waiting thread wakes up.
356 /// If the value no longer matches the requested value when the
357 /// waiting thread wakes up, it will go back into a wait state. It
358 /// may be necessary for the calling code to use additional thread
359 /// synchronization methods to detect transitory states.
362 /// The value we want \a m_value to be equal to.
364 /// @param[in] new_value
365 /// The value to which \a m_value will be set if \b true is
368 /// @param[in] abstime
369 /// If non-NULL, the absolute time at which we should stop
370 /// waiting, else wait an infinite amount of time.
372 /// @param[out] timed_out
373 /// If not null, set to true if we return because of a time out,
374 /// and false if the value was set.
377 /// @li \b true if the \a m_value became equal to \a value
378 /// @li \b false otherwise
379 //------------------------------------------------------------------
381 WaitForValueEqualToAndSetValueTo (T wait_value, T new_value, const TimeValue *abstime = NULL, bool *timed_out = NULL)
384 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
385 // unlock the mutex and wait for the condition to be set. When either
386 // function returns, they will re-lock the mutex. We use an auto lock/unlock
387 // class (Mutex::Locker) to allow us to return at any point in this
388 // function and not have to worry about unlocking the mutex.
389 Mutex::Locker locker(m_mutex);
391 #ifdef DB_PTHREAD_LOG_EVENTS
392 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);
397 while (err == 0 && m_value != wait_value)
399 err = m_condition.Wait (m_mutex, abstime, timed_out);
402 if (m_value == wait_value)
412 //------------------------------------------------------------------
413 /// Wait for \a m_value to not be equal to \a value.
415 /// Waits in a thread safe way for \a m_value to not be equal to \a
416 /// value. If \a m_value is already not equal to \a value, this
417 /// function will return without waiting.
419 /// It is possible for the value to be changed between the time
420 /// the value is set and the time the waiting thread wakes up.
421 /// If the value is equal to the test value when the waiting thread
422 /// wakes up, it will go back into a wait state. It may be
423 /// necessary for the calling code to use additional thread
424 /// synchronization methods to detect transitory states.
427 /// The value we want \a m_value to not be equal to.
429 /// @param[out] new_value
430 /// The new value if \b true is returned.
432 /// @param[in] abstime
433 /// If non-NULL, the absolute time at which we should stop
434 /// waiting, else wait an infinite amount of time.
437 /// @li \b true if the \a m_value is equal to \a value
438 /// @li \b false otherwise
439 //------------------------------------------------------------------
441 WaitForValueNotEqualTo (T value, T &new_value, const TimeValue *abstime = NULL)
444 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
445 // unlock the mutex and wait for the condition to be set. When either
446 // function returns, they will re-lock the mutex. We use an auto lock/unlock
447 // class (Mutex::Locker) to allow us to return at any point in this
448 // function and not have to worry about unlocking the mutex.
449 Mutex::Locker locker(m_mutex);
450 #ifdef DB_PTHREAD_LOG_EVENTS
451 printf("%s (value = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, value, abstime, m_value);
453 while (err == 0 && m_value == value)
455 err = m_condition.Wait (m_mutex, abstime);
458 if (m_value != value)
467 //----------------------------------------------------------------------
468 // pthread condition and mutex variable to control access and allow
469 // blocking between the main thread and the spotlight index thread.
470 //----------------------------------------------------------------------
471 T m_value; ///< The templatized value T that we are protecting access to
472 mutable Mutex m_mutex; ///< The mutex to use when accessing the data
473 Condition m_condition; ///< The pthread condition variable to use for signaling that data available or changed.
477 //------------------------------------------------------------------
478 /// Broadcast if needed.
480 /// Check to see if we need to broadcast to our condition variable
481 /// depending on the \a old_value and on the \a broadcast_type.
483 /// If \a broadcast_type is eBroadcastNever, no broadcast will be
486 /// If \a broadcast_type is eBroadcastAlways, the condition variable
487 /// will always be broadcast.
489 /// If \a broadcast_type is eBroadcastOnChange, the condition
490 /// variable be broadcast if the owned value changes.
491 //------------------------------------------------------------------
493 Broadcast (T old_value, PredicateBroadcastType broadcast_type)
495 bool broadcast = (broadcast_type == eBroadcastAlways) || ((broadcast_type == eBroadcastOnChange) && old_value != m_value);
496 #ifdef DB_PTHREAD_LOG_EVENTS
497 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);
500 m_condition.Broadcast();
504 DISALLOW_COPY_AND_ASSIGN(Predicate);
507 } // namespace lldb_private
509 #endif // #if defined(__cplusplus)
510 #endif // #ifndef liblldb_Predicate_h_