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/Host/Mutex.h"
15 #include "lldb/Host/Condition.h"
19 //#define DB_PTHREAD_LOG_EVENTS
21 //----------------------------------------------------------------------
22 /// Enumerations for broadcasting.
23 //----------------------------------------------------------------------
24 namespace lldb_private {
28 eBroadcastNever, ///< No broadcast will be sent when the value is modified.
29 eBroadcastAlways, ///< Always send a broadcast when the value is modified.
30 eBroadcastOnChange ///< Only broadcast if the value changes when the value is modified.
32 } PredicateBroadcastType;
34 //----------------------------------------------------------------------
35 /// @class Predicate Predicate.h "lldb/Host/Predicate.h"
36 /// @brief A C++ wrapper class for providing threaded access to a value
39 /// A templatized class that provides multi-threaded access to a value
40 /// of type T. Threads can efficiently wait for bits within T to be set
41 /// or reset, or wait for T to be set to be equal/not equal to a
43 //----------------------------------------------------------------------
49 //------------------------------------------------------------------
50 /// Default constructor.
52 /// Initializes the mutex, condition and value with their default
54 //------------------------------------------------------------------
62 //------------------------------------------------------------------
63 /// Construct with initial T value \a initial_value.
65 /// Initializes the mutex and condition with their default
66 /// constructors, and initializes the value with \a initial_value.
68 /// @param[in] initial_value
69 /// The initial value for our T object.
70 //------------------------------------------------------------------
71 Predicate (T initial_value) :
72 m_value(initial_value),
78 //------------------------------------------------------------------
81 /// Destrory the condition, mutex, and T objects.
82 //------------------------------------------------------------------
88 //------------------------------------------------------------------
89 /// Value get accessor.
91 /// Copies the current \a m_value in a thread safe manor and returns
95 /// A copy of the current value.
96 //------------------------------------------------------------------
100 Mutex::Locker locker(m_mutex);
105 //------------------------------------------------------------------
106 /// Value set accessor.
108 /// Set the contained \a m_value to \a new_value in a thread safe
109 /// way and broadcast if needed.
112 /// The new value to set.
114 /// @param[in] broadcast_type
115 /// A value indicating when and if to broadast. See the
116 /// PredicateBroadcastType enumeration for details.
118 /// @see Predicate::Broadcast()
119 //------------------------------------------------------------------
121 SetValue (T value, PredicateBroadcastType broadcast_type)
123 Mutex::Locker locker(m_mutex);
124 #ifdef DB_PTHREAD_LOG_EVENTS
125 printf("%s (value = 0x%8.8x, broadcast_type = %i)\n", __FUNCTION__, value, broadcast_type);
127 const T old_value = m_value;
130 Broadcast(old_value, broadcast_type);
133 //------------------------------------------------------------------
134 /// Set some bits in \a m_value.
136 /// Logically set the bits \a bits in the contained \a m_value in a
137 /// thread safe way and broadcast if needed.
140 /// The bits to set in \a m_value.
142 /// @param[in] broadcast_type
143 /// A value indicating when and if to broadast. See the
144 /// PredicateBroadcastType enumeration for details.
146 /// @see Predicate::Broadcast()
147 //------------------------------------------------------------------
149 SetValueBits (T bits, PredicateBroadcastType broadcast_type)
151 Mutex::Locker locker(m_mutex);
152 #ifdef DB_PTHREAD_LOG_EVENTS
153 printf("%s (bits = 0x%8.8x, broadcast_type = %i)\n", __FUNCTION__, bits, broadcast_type);
155 const T old_value = m_value;
158 Broadcast(old_value, broadcast_type);
161 //------------------------------------------------------------------
162 /// Reset some bits in \a m_value.
164 /// Logically reset (clear) the bits \a bits in the contained
165 /// \a m_value in a thread safe way and broadcast if needed.
168 /// The bits to clear in \a m_value.
170 /// @param[in] broadcast_type
171 /// A value indicating when and if to broadast. See the
172 /// PredicateBroadcastType enumeration for details.
174 /// @see Predicate::Broadcast()
175 //------------------------------------------------------------------
177 ResetValueBits (T bits, PredicateBroadcastType broadcast_type)
179 Mutex::Locker locker(m_mutex);
180 #ifdef DB_PTHREAD_LOG_EVENTS
181 printf("%s (bits = 0x%8.8x, broadcast_type = %i)\n", __FUNCTION__, bits, broadcast_type);
183 const T old_value = m_value;
186 Broadcast(old_value, broadcast_type);
189 //------------------------------------------------------------------
190 /// Wait for bits to be set in \a m_value.
192 /// Waits in a thread safe way for any bits in \a bits to get
193 /// logically set in \a m_value. If any bits are already set in
194 /// \a m_value, this function will return without waiting.
196 /// It is possible for the value to be changed between the time
197 /// the bits are set and the time the waiting thread wakes up.
198 /// If the bits are no longer set when the waiting thread wakes
199 /// up, it will go back into a wait state. It may be necessary
200 /// for the calling code to use additional thread synchronization
201 /// methods to detect transitory states.
204 /// The bits we are waiting to be set in \a m_value.
206 /// @param[in] abstime
207 /// If non-NULL, the absolute time at which we should stop
208 /// waiting, else wait an infinite amount of time.
211 /// Any bits of the requested bits that actually were set within
212 /// the time specified. Zero if a timeout or unrecoverable error
214 //------------------------------------------------------------------
216 WaitForSetValueBits (T bits, const TimeValue *abstime = NULL)
219 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
220 // unlock the mutex and wait for the condition to be set. When either
221 // function returns, they will re-lock the mutex. We use an auto lock/unlock
222 // class (Mutex::Locker) to allow us to return at any point in this
223 // function and not have to worry about unlocking the mutex.
224 Mutex::Locker locker(m_mutex);
225 #ifdef DB_PTHREAD_LOG_EVENTS
226 printf("%s (bits = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, bits, abstime, m_value);
228 while (err == 0 && ((m_value & bits) == 0))
230 err = m_condition.Wait (m_mutex, abstime);
232 #ifdef DB_PTHREAD_LOG_EVENTS
233 printf("%s (bits = 0x%8.8x), m_value = 0x%8.8x, returning 0x%8.8x\n", __FUNCTION__, bits, m_value, m_value & bits);
236 return m_value & bits;
239 //------------------------------------------------------------------
240 /// Wait for bits to be reset in \a m_value.
242 /// Waits in a thread safe way for any bits in \a bits to get
243 /// logically reset in \a m_value. If all bits are already reset in
244 /// \a m_value, this function will return without waiting.
246 /// It is possible for the value to be changed between the time
247 /// the bits are reset and the time the waiting thread wakes up.
248 /// If the bits are no set when the waiting thread wakes up, it will
249 /// go back into a wait state. It may be necessary for the calling
250 /// code to use additional thread synchronization methods to detect
251 /// transitory states.
254 /// The bits we are waiting to be reset in \a m_value.
256 /// @param[in] abstime
257 /// If non-NULL, the absolute time at which we should stop
258 /// waiting, else wait an infinite amount of time.
261 /// Zero on successful waits, or non-zero if a timeout or
262 /// unrecoverable error occurs.
263 //------------------------------------------------------------------
265 WaitForResetValueBits (T bits, const TimeValue *abstime = NULL)
269 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
270 // unlock the mutex and wait for the condition to be set. When either
271 // function returns, they will re-lock the mutex. We use an auto lock/unlock
272 // class (Mutex::Locker) to allow us to return at any point in this
273 // function and not have to worry about unlocking the mutex.
274 Mutex::Locker locker(m_mutex);
276 #ifdef DB_PTHREAD_LOG_EVENTS
277 printf("%s (bits = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, bits, abstime, m_value);
279 while (err == 0 && ((m_value & bits) != 0))
281 err = m_condition.Wait (m_mutex, abstime);
284 #ifdef DB_PTHREAD_LOG_EVENTS
285 printf("%s (bits = 0x%8.8x), m_value = 0x%8.8x, returning 0x%8.8x\n", __FUNCTION__, bits, m_value, m_value & bits);
287 return m_value & bits;
290 //------------------------------------------------------------------
291 /// Wait for \a m_value to be equal to \a value.
293 /// Waits in a thread safe way for \a m_value to be equal to \a
294 /// value. If \a m_value is already equal to \a value, this
295 /// function will return without waiting.
297 /// It is possible for the value to be changed between the time
298 /// the value is set and the time the waiting thread wakes up.
299 /// If the value no longer matches the requested value when the
300 /// waiting thread wakes up, it will go back into a wait state. It
301 /// may be necessary for the calling code to use additional thread
302 /// synchronization methods to detect transitory states.
305 /// The value we want \a m_value to be equal to.
307 /// @param[in] abstime
308 /// If non-NULL, the absolute time at which we should stop
309 /// waiting, else wait an infinite amount of time.
311 /// @param[out] timed_out
312 /// If not null, set to true if we return because of a time out,
313 /// and false if the value was set.
316 /// @li \b true if the \a m_value is equal to \a value
317 /// @li \b false otherwise
318 //------------------------------------------------------------------
320 WaitForValueEqualTo (T value, const TimeValue *abstime = NULL, bool *timed_out = NULL)
323 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
324 // unlock the mutex and wait for the condition to be set. When either
325 // function returns, they will re-lock the mutex. We use an auto lock/unlock
326 // class (Mutex::Locker) to allow us to return at any point in this
327 // function and not have to worry about unlocking the mutex.
328 Mutex::Locker locker(m_mutex);
330 #ifdef DB_PTHREAD_LOG_EVENTS
331 printf("%s (value = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, value, abstime, m_value);
336 while (err == 0 && m_value != value)
338 err = m_condition.Wait (m_mutex, abstime, timed_out);
341 return m_value == value;
344 //------------------------------------------------------------------
345 /// Wait for \a m_value to be equal to \a value and then set it to
348 /// Waits in a thread safe way for \a m_value to be equal to \a
349 /// value and then sets \a m_value to \a new_value. If \a m_value
350 /// is already equal to \a value, this function will immediately
351 /// set \a m_value to \a new_value and return without waiting.
353 /// It is possible for the value to be changed between the time
354 /// the value is set and the time the waiting thread wakes up.
355 /// If the value no longer matches the requested value when the
356 /// waiting thread wakes up, it will go back into a wait state. It
357 /// may be necessary for the calling code to use additional thread
358 /// synchronization methods to detect transitory states.
361 /// The value we want \a m_value to be equal to.
363 /// @param[in] new_value
364 /// The value to which \a m_value will be set if \b true is
367 /// @param[in] abstime
368 /// If non-NULL, the absolute time at which we should stop
369 /// waiting, else wait an infinite amount of time.
371 /// @param[out] timed_out
372 /// If not null, set to true if we return because of a time out,
373 /// and false if the value was set.
376 /// @li \b true if the \a m_value became equal to \a value
377 /// @li \b false otherwise
378 //------------------------------------------------------------------
380 WaitForValueEqualToAndSetValueTo (T wait_value, T new_value, const TimeValue *abstime = NULL, bool *timed_out = NULL)
383 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
384 // unlock the mutex and wait for the condition to be set. When either
385 // function returns, they will re-lock the mutex. We use an auto lock/unlock
386 // class (Mutex::Locker) to allow us to return at any point in this
387 // function and not have to worry about unlocking the mutex.
388 Mutex::Locker locker(m_mutex);
390 #ifdef DB_PTHREAD_LOG_EVENTS
391 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);
396 while (err == 0 && m_value != wait_value)
398 err = m_condition.Wait (m_mutex, abstime, timed_out);
401 if (m_value == wait_value)
411 //------------------------------------------------------------------
412 /// Wait for \a m_value to not be equal to \a value.
414 /// Waits in a thread safe way for \a m_value to not be equal to \a
415 /// value. If \a m_value is already not equal to \a value, this
416 /// function will return without waiting.
418 /// It is possible for the value to be changed between the time
419 /// the value is set and the time the waiting thread wakes up.
420 /// If the value is equal to the test value when the waiting thread
421 /// wakes up, it will go back into a wait state. It may be
422 /// necessary for the calling code to use additional thread
423 /// synchronization methods to detect transitory states.
426 /// The value we want \a m_value to not be equal to.
428 /// @param[out] new_value
429 /// The new value if \b true is returned.
431 /// @param[in] abstime
432 /// If non-NULL, the absolute time at which we should stop
433 /// waiting, else wait an infinite amount of time.
436 /// @li \b true if the \a m_value is equal to \a value
437 /// @li \b false otherwise
438 //------------------------------------------------------------------
440 WaitForValueNotEqualTo (T value, T &new_value, const TimeValue *abstime = NULL)
443 // pthread_cond_timedwait() or pthread_cond_wait() will atomically
444 // unlock the mutex and wait for the condition to be set. When either
445 // function returns, they will re-lock the mutex. We use an auto lock/unlock
446 // class (Mutex::Locker) to allow us to return at any point in this
447 // function and not have to worry about unlocking the mutex.
448 Mutex::Locker locker(m_mutex);
449 #ifdef DB_PTHREAD_LOG_EVENTS
450 printf("%s (value = 0x%8.8x, abstime = %p), m_value = 0x%8.8x\n", __FUNCTION__, value, abstime, m_value);
452 while (err == 0 && m_value == value)
454 err = m_condition.Wait (m_mutex, abstime);
457 if (m_value != value)
466 //----------------------------------------------------------------------
467 // pthread condition and mutex variable to controll access and allow
468 // blocking between the main thread and the spotlight index thread.
469 //----------------------------------------------------------------------
470 T m_value; ///< The templatized value T that we are protecting access to
471 mutable Mutex m_mutex; ///< The mutex to use when accessing the data
472 Condition m_condition; ///< The pthread condition variable to use for signaling that data available or changed.
476 //------------------------------------------------------------------
477 /// Broadcast if needed.
479 /// Check to see if we need to broadcast to our condition variable
480 /// depedning on the \a old_value and on the \a broadcast_type.
482 /// If \a broadcast_type is eBroadcastNever, no broadcast will be
485 /// If \a broadcast_type is eBroadcastAlways, the condition variable
486 /// will always be broadcast.
488 /// If \a broadcast_type is eBroadcastOnChange, the condition
489 /// variable be broadcast if the owned value changes.
490 //------------------------------------------------------------------
492 Broadcast (T old_value, PredicateBroadcastType broadcast_type)
494 bool broadcast = (broadcast_type == eBroadcastAlways) || ((broadcast_type == eBroadcastOnChange) && old_value != m_value);
495 #ifdef DB_PTHREAD_LOG_EVENTS
496 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);
499 m_condition.Broadcast();
503 DISALLOW_COPY_AND_ASSIGN(Predicate);
506 } // namespace lldb_private
508 #endif // #if defined(__cplusplus)
509 #endif // #ifndef liblldb_Predicate_h_