1 // Copyright 2013 The Flutter 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 // Macros for static thread-safety analysis. 6 // 7 // These are from http://clang.llvm.org/docs/ThreadSafetyAnalysis.html (and thus 8 // really derive from google3's thread_annotations.h). 9 // 10 // TODO(vtl): We're still using the old-fashioned, deprecated annotations 11 // ("locks" instead of "capabilities"), since the new ones don't work yet (in 12 // particular, |TRY_ACQUIRE()| doesn't work: b/19264527). 13 // https://github.com/domokit/mojo/issues/314 14 15 #ifndef FLUTTER_FML_SYNCHRONIZATION_THREAD_ANNOTATIONS_H_ 16 #define FLUTTER_FML_SYNCHRONIZATION_THREAD_ANNOTATIONS_H_ 17 18 #include "flutter/fml/build_config.h" 19 20 // Enable thread-safety attributes only with clang. 21 // The attributes can be safely erased when compiling with other compilers. 22 #if defined(__clang__) && !defined(OS_ANDROID) 23 #define FML_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) 24 #else 25 #define FML_THREAD_ANNOTATION_ATTRIBUTE__(x) 26 #endif 27 28 #define FML_GUARDED_BY(x) FML_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) 29 30 #define FML_PT_GUARDED_BY(x) FML_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) 31 32 #define FML_ACQUIRE(...) \ 33 FML_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(__VA_ARGS__)) 34 35 #define FML_RELEASE(...) \ 36 FML_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__)) 37 38 #define FML_ACQUIRED_AFTER(...) \ 39 FML_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__)) 40 41 #define FML_ACQUIRED_BEFORE(...) \ 42 FML_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__)) 43 44 #define FML_EXCLUSIVE_LOCKS_REQUIRED(...) \ 45 FML_THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__)) 46 47 #define FML_SHARED_LOCKS_REQUIRED(...) \ 48 FML_THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__)) 49 50 #define FML_LOCKS_EXCLUDED(...) \ 51 FML_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__)) 52 53 #define FML_LOCK_RETURNED(x) FML_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) 54 55 #define FML_LOCKABLE FML_THREAD_ANNOTATION_ATTRIBUTE__(lockable) 56 57 #define FML_SCOPED_LOCKABLE FML_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) 58 59 #define FML_EXCLUSIVE_LOCK_FUNCTION(...) \ 60 FML_THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__)) 61 62 #define FML_SHARED_LOCK_FUNCTION(...) \ 63 FML_THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__)) 64 65 #define FML_ASSERT_EXCLUSIVE_LOCK(...) \ 66 FML_THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__)) 67 68 #define FML_ASSERT_SHARED_LOCK(...) \ 69 FML_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__)) 70 71 #define FML_EXCLUSIVE_TRYLOCK_FUNCTION(...) \ 72 FML_THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__)) 73 74 #define FML_SHARED_TRYLOCK_FUNCTION(...) \ 75 FML_THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__)) 76 77 #define FML_UNLOCK_FUNCTION(...) \ 78 FML_THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__)) 79 80 #define FML_NO_THREAD_SAFETY_ANALYSIS \ 81 FML_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) 82 83 // Use this in the header to annotate a function/method as not being 84 // thread-safe. This is equivalent to |FML_NO_THREAD_SAFETY_ANALYSIS|, but 85 // semantically different: it declares that the caller must abide by additional 86 // restrictions. Limitation: Unfortunately, you can't apply this to a method in 87 // an interface (i.e., pure virtual method) and have it applied automatically to 88 // implementations. 89 #define FML_NOT_THREAD_SAFE FML_NO_THREAD_SAFETY_ANALYSIS 90 91 #endif // FLUTTER_FML_SYNCHRONIZATION_THREAD_ANNOTATIONS_H_ 92