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