1 //===-- Mutex.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_Mutex_h_
11 #define liblldb_Mutex_h_
15 #ifdef LLDB_CONFIGURATION_DEBUG
19 // Other libraries and framework includes
21 #include "lldb/lldb-types.h"
23 namespace lldb_private {
25 //----------------------------------------------------------------------
26 /// @class Mutex Mutex.h "lldb/Host/Mutex.h"
27 /// @brief A C++ wrapper class for pthread mutexes.
28 //----------------------------------------------------------------------
33 friend class Condition;
37 eMutexTypeNormal, ///< Mutex that can't recursively entered by the same thread
38 eMutexTypeRecursive ///< Mutex can be recursively entered by the same thread
41 //------------------------------------------------------------------
42 /// @class Mutex::Locker
44 /// A scoped locking class that allows a variety of pthread mutex
45 /// objects to have a mutex locked when an Mutex::Locker
46 /// object is created, and unlocked when it goes out of scope or
47 /// when the Mutex::Locker::Reset(pthread_mutex_t *)
48 /// is called. This provides an exception safe way to lock a mutex
50 //------------------------------------------------------------------
54 //--------------------------------------------------------------
55 /// Default constructor.
57 /// This will create a scoped mutex locking object that doesn't
58 /// have a mutex to lock. One will need to be provided using the
59 /// Mutex::Locker::Reset(pthread_mutex_t *) method.
61 /// @see Mutex::Locker::Reset(pthread_mutex_t *)
62 //--------------------------------------------------------------
65 //--------------------------------------------------------------
66 /// Constructor with a Mutex object.
68 /// This will create a scoped mutex locking object that extracts
69 /// the mutex owned by \a m and locks it.
72 /// An instance of a Mutex object that contains a
73 /// valid mutex object.
74 //--------------------------------------------------------------
77 //--------------------------------------------------------------
78 /// Constructor with a Mutex object pointer.
80 /// This will create a scoped mutex locking object that extracts
81 /// the mutex owned by a m and locks it.
84 /// A pointer to instance of a Mutex object that
85 /// contains a valid mutex object.
86 //--------------------------------------------------------------
89 //--------------------------------------------------------------
92 /// Unlocks any valid pthread_mutex_t that this object may
94 //--------------------------------------------------------------
97 //--------------------------------------------------------------
98 /// Change the contained mutex.
100 /// Unlock the current mutex in this object (if it contains a
101 /// valid mutex) and lock the new \a mutex object if it is
103 //--------------------------------------------------------------
114 //--------------------------------------------------------------
115 /// Change the contained mutex only if the mutex can be locked.
117 /// Unlock the current mutex in this object (if it contains a
118 /// valid mutex) and try to lock \a mutex. If \a mutex can be
119 /// locked this object will take ownership of the lock and will
120 /// unlock it when it goes out of scope or Reset or TryLock are
121 /// called again. If the mutex is already locked, this object
122 /// will not take ownership of the mutex.
125 /// Returns \b true if the lock was acquired and the this
126 /// object will unlock the mutex when it goes out of scope,
127 /// returns \b false otherwise.
128 //--------------------------------------------------------------
130 TryLock(Mutex &mutex, const char *failure_message = nullptr);
133 TryLock(Mutex *mutex, const char *failure_message = nullptr)
136 return TryLock(*mutex, failure_message);
145 //--------------------------------------------------------------
147 //--------------------------------------------------------------
151 Locker(const Locker&);
152 const Locker& operator=(const Locker&);
155 //------------------------------------------------------------------
156 /// Default constructor.
158 /// Creates a pthread mutex with no attributes.
159 //------------------------------------------------------------------
162 //------------------------------------------------------------------
163 /// Default constructor.
165 /// Creates a pthread mutex with \a type as the mutex type.
166 /// Valid values for \a type include:
167 /// @li Mutex::Type::eMutexTypeNormal
168 /// @li Mutex::Type::eMutexTypeRecursive
171 /// The type of the mutex.
173 /// @see ::pthread_mutexattr_settype()
174 //------------------------------------------------------------------
175 Mutex(Mutex::Type type);
177 //------------------------------------------------------------------
180 /// Destroys the mutex owned by this object.
181 //------------------------------------------------------------------
182 #ifdef LLDB_CONFIGURATION_DEBUG
187 //------------------------------------------------------------------
190 /// Locks the mutex owned by this object. If the mutex is already
191 /// locked, the calling thread will block until the mutex becomes
195 /// The error code from \c pthread_mutex_lock().
196 //------------------------------------------------------------------
197 #ifdef LLDB_CONFIGURATION_DEBUG
203 //------------------------------------------------------------------
204 /// Try to lock the mutex.
206 /// Attempts to lock the mutex owned by this object without blocking.
207 /// If the mutex is already locked, TryLock() will not block waiting
208 /// for the mutex, but will return an error condition.
211 /// The error code from \c pthread_mutex_trylock().
212 //------------------------------------------------------------------
213 #ifdef LLDB_CONFIGURATION_DEBUG
217 TryLock(const char *failure_message = nullptr);
219 //------------------------------------------------------------------
220 /// Unlock the mutex.
222 /// If the current thread holds the lock on the owned mutex, then
223 /// Unlock() will unlock the mutex. Calling Unlock() on this object
224 /// when the calling thread does not hold the lock will result in
225 /// undefined behavior.
228 /// The error code from \c pthread_mutex_unlock().
229 //------------------------------------------------------------------
230 #ifdef LLDB_CONFIGURATION_DEBUG
237 //------------------------------------------------------------------
239 //------------------------------------------------------------------
240 // TODO: Hide the mutex in the implementation file in case we ever need to port to an
241 // architecture that doesn't have pthread mutexes.
242 lldb::mutex_t m_mutex; ///< The OS mutex object.
245 //------------------------------------------------------------------
246 /// Mutex get accessor.
249 /// A pointer to the pthread mutex object owned by this object.
250 //------------------------------------------------------------------
255 const Mutex& operator=(const Mutex&);
258 #ifdef LLDB_CONFIGURATION_DEBUG
259 class TrackingMutex : public Mutex
262 TrackingMutex() : Mutex() {}
263 TrackingMutex(Mutex::Type type) : Mutex (type) {}
266 ~TrackingMutex() = default;
272 TryLock(const char *failure_message = nullptr)
274 int return_value = Mutex::TryLock();
275 if (return_value != 0 && failure_message != nullptr)
277 m_failure_message.assign(failure_message);
278 m_thread_that_tried = pthread_self();
284 pthread_t m_thread_that_tried;
285 std::string m_failure_message;
288 class LoggingMutex : public Mutex
291 LoggingMutex() : Mutex(),m_locked(false) {}
292 LoggingMutex(Mutex::Type type) : Mutex (type),m_locked(false) {}
295 ~LoggingMutex() = default;
304 TryLock(const char *failure_message = nullptr);
309 #endif // LLDB_CONFIGURATION_DEBUG
311 } // namespace lldb_private
313 #endif // liblldb_Mutex_h_