1// Taken from https://clang.llvm.org/docs/ThreadSafetyAnalysis.html
2
3#ifndef BASE_LOCK_H
4#define BASE_LOCK_H
5
6#include <mutex>
7
8// Enable thread safety attributes only with clang.
9// The attributes can be safely erased when compiling with other compilers.
10#if defined(__clang__) && (!defined(SWIG))
11#define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
12#else
13#define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op
14#endif
15
16#define CAPABILITY(x) \
17 THREAD_ANNOTATION_ATTRIBUTE__(capability(x))
18
19#define SCOPED_CAPABILITY \
20 THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
21
22#define GUARDED_BY(x) \
23 THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
24
25#define PT_GUARDED_BY(x) \
26 THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
27
28#define ACQUIRED_BEFORE(...) \
29 THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
30
31#define ACQUIRED_AFTER(...) \
32 THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
33
34#define REQUIRES(...) \
35 THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(__VA_ARGS__))
36
37#define REQUIRES_SHARED(...) \
38 THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(__VA_ARGS__))
39
40#define ACQUIRE(...) \
41 THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(__VA_ARGS__))
42
43#define ACQUIRE_SHARED(...) \
44 THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__))
45
46#define RELEASE(...) \
47 THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))
48
49#define RELEASE_SHARED(...) \
50 THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))
51
52#define RELEASE_GENERIC(...) \
53 THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(__VA_ARGS__))
54
55#define TRY_ACQUIRE(...) \
56 THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__))
57
58#define TRY_ACQUIRE_SHARED(...) \
59 THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__))
60
61#define EXCLUDES(...) \
62 THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
63
64#define ASSERT_CAPABILITY(x) \
65 THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))
66
67#define ASSERT_SHARED_CAPABILITY(x) \
68 THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))
69
70#define RETURN_CAPABILITY(x) \
71 THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
72
73#define NO_THREAD_SAFETY_ANALYSIS \
74 THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
75
76/**
77 * @defgroup Locks Locks
78 * @see Threads
79 */
80
81/**
82 * Wrapper for `std::mutex`.
83 *
84 * @ingroup Locks
85 *
86 * @remark This wrapper is only necessary because the clang thread-safety attributes
87 * are not available for `std::mutex` except when explicitly using libc++.
88 */
89class CAPABILITY("mutex") CLock
90{
91public:
92 CLock() = default;
93
94 void lock() ACQUIRE()
95 {
96 m_Mutex.lock();
97 }
98
99 void unlock() RELEASE()
100 {
101 m_Mutex.unlock();
102 }
103
104 // To support negative capabilities, otherwise EXCLUDES(m_Lock) must be used instead of REQUIRES(!m_Lock)
105 const CLock &operator!() const { return *this; }
106
107private:
108 std::mutex m_Mutex;
109};
110
111/**
112 * RAII-style wrapper for owning a `CLock`.
113 *
114 * @ingroup Locks
115 *
116 * @remark This wrapper is only necessary because the clang thread-safety attributes
117 * are not available for `std::lock_guard` except when explicitly using libc++.
118 */
119class SCOPED_CAPABILITY CLockScope
120{
121public:
122 explicit CLockScope(CLock &Lock) ACQUIRE(Lock, m_Lock) :
123 m_Lock(Lock)
124 {
125 m_Lock.lock();
126 }
127
128 ~CLockScope() RELEASE() REQUIRES(m_Lock)
129 {
130 m_Lock.unlock();
131 }
132
133 CLockScope(const CLockScope &) = delete;
134
135private:
136 CLock &m_Lock;
137};
138
139#endif
140