1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef BASE_SYNCHRONIZATION_LOCK_H_
6 #define BASE_SYNCHRONIZATION_LOCK_H_
7 
8 #include "base/base_export.h"
9 #include "base/logging.h"
10 #include "base/macros.h"
11 #include "base/synchronization/lock_impl.h"
12 #include "base/thread_annotations.h"
13 #include "base/threading/platform_thread.h"
14 #include "build/build_config.h"
15 
16 namespace base {
17 
18 // A convenient wrapper for an OS specific critical section.  The only real
19 // intelligence in this class is in debug mode for the support for the
20 // AssertAcquired() method.
21 class LOCKABLE BASE_EXPORT Lock {
22  public:
23 #if !DCHECK_IS_ON()
24   // Optimized wrapper implementation
Lock()25   Lock() : lock_() {}
~Lock()26   ~Lock() {}
27 
28   // TODO(lukasza): https://crbug.com/831825: Add EXCLUSIVE_LOCK_FUNCTION
29   // annotation to Acquire method and similar annotations to Release and Try
30   // methods (here and in the #else branch).
Acquire()31   void Acquire() { lock_.Lock(); }
Release()32   void Release() { lock_.Unlock(); }
33 
34   // If the lock is not held, take it and return true. If the lock is already
35   // held by another thread, immediately return false. This must not be called
36   // by a thread already holding the lock (what happens is undefined and an
37   // assertion may fail).
Try()38   bool Try() { return lock_.Try(); }
39 
40   // Null implementation if not debug.
AssertAcquired()41   void AssertAcquired() const ASSERT_EXCLUSIVE_LOCK() {}
42 #else
43   Lock();
44   ~Lock();
45 
46   // NOTE: We do not permit recursive locks and will commonly fire a DCHECK() if
47   // a thread attempts to acquire the lock a second time (while already holding
48   // it).
49   void Acquire() {
50     lock_.Lock();
51     CheckUnheldAndMark();
52   }
53   void Release() {
54     CheckHeldAndUnmark();
55     lock_.Unlock();
56   }
57 
58   bool Try() {
59     bool rv = lock_.Try();
60     if (rv) {
61       CheckUnheldAndMark();
62     }
63     return rv;
64   }
65 
66   void AssertAcquired() const ASSERT_EXCLUSIVE_LOCK();
67 #endif  // DCHECK_IS_ON()
68 
69   // Whether Lock mitigates priority inversion when used from different thread
70   // priorities.
HandlesMultipleThreadPriorities()71   static bool HandlesMultipleThreadPriorities() {
72 #if defined(OS_WIN)
73     // Windows mitigates priority inversion by randomly boosting the priority of
74     // ready threads.
75     // https://msdn.microsoft.com/library/windows/desktop/ms684831.aspx
76     return true;
77 #elif defined(OS_POSIX) || defined(OS_FUCHSIA)
78     // POSIX mitigates priority inversion by setting the priority of a thread
79     // holding a Lock to the maximum priority of any other thread waiting on it.
80     return internal::LockImpl::PriorityInheritanceAvailable();
81 #else
82 #error Unsupported platform
83 #endif
84   }
85 
86   // Both Windows and POSIX implementations of ConditionVariable need to be
87   // able to see our lock and tweak our debugging counters, as they release and
88   // acquire locks inside of their condition variable APIs.
89   friend class ConditionVariable;
90 
91  private:
92 #if DCHECK_IS_ON()
93   // Members and routines taking care of locks assertions.
94   // Note that this checks for recursive locks and allows them
95   // if the variable is set.  This is allowed by the underlying implementation
96   // on windows but not on Posix, so we're doing unneeded checks on Posix.
97   // It's worth it to share the code.
98   void CheckHeldAndUnmark();
99   void CheckUnheldAndMark();
100 
101   // All private data is implicitly protected by lock_.
102   // Be VERY careful to only access members under that lock.
103   base::PlatformThreadRef owning_thread_ref_;
104 #endif  // DCHECK_IS_ON()
105 
106   // Platform specific underlying lock implementation.
107   internal::LockImpl lock_;
108 
109   DISALLOW_COPY_AND_ASSIGN(Lock);
110 };
111 
112 // A helper class that acquires the given Lock while the AutoLock is in scope.
113 using AutoLock = internal::BasicAutoLock<Lock>;
114 
115 // AutoUnlock is a helper that will Release() the |lock| argument in the
116 // constructor, and re-Acquire() it in the destructor.
117 using AutoUnlock = internal::BasicAutoUnlock<Lock>;
118 
119 // Like AutoLock but is a no-op when the provided Lock* is null. Inspired from
120 // absl::MutexLockMaybe. Use this instead of base::Optional<base::AutoLock> to
121 // get around -Wthread-safety-analysis warnings for conditional locking.
122 using AutoLockMaybe = internal::BasicAutoLockMaybe<Lock>;
123 
124 // Like AutoLock but permits Release() of its mutex before destruction.
125 // Release() may be called at most once. Inspired from
126 // absl::ReleasableMutexLock. Use this instead of base::Optional<base::AutoLock>
127 // to get around -Wthread-safety-analysis warnings for AutoLocks that are
128 // explicitly released early (prefer proper scoping to this).
129 using ReleasableAutoLock = internal::BasicReleasableAutoLock<Lock>;
130 
131 }  // namespace base
132 
133 #endif  // BASE_SYNCHRONIZATION_LOCK_H_
134