|
| 1 | +// Note: the file is largely imported directly from WebRTC upstream, so |
| 2 | +// comments may not completely apply to Mozilla's usage. |
| 3 | +// |
| 4 | +// Copyright (c) 2013 The WebRTC project authors. All Rights Reserved. |
| 5 | +// |
| 6 | +// Use of this source code is governed by a BSD-style license |
| 7 | +// that can be found in the LICENSE file in the root of the source |
| 8 | +// tree. An additional intellectual property rights grant can be found |
| 9 | +// in the file PATENTS. All contributing project authors may |
| 10 | +// be found in the AUTHORS file in the root of the source tree. |
| 11 | +// |
| 12 | +// Borrowed from |
| 13 | +// https://code.google.com/p/gperftools/source/browse/src/base/thread_annotations.h |
| 14 | +// but adapted for clang attributes instead of the gcc. |
| 15 | +// |
| 16 | +// This header file contains the macro definitions for thread safety |
| 17 | +// annotations that allow the developers to document the locking policies |
| 18 | +// of their multi-threaded code. The annotations can also help program |
| 19 | +// analysis tools to identify potential thread safety issues. |
| 20 | + |
| 21 | +#ifndef mozilla_ThreadSafety_h |
| 22 | +#define mozilla_ThreadSafety_h |
| 23 | +#include "mozilla/Attributes.h" |
| 24 | + |
| 25 | +#if defined(__clang__) && (!defined(SWIG)) |
| 26 | +# define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) |
| 27 | +// Allow for localized suppression of thread-safety warnings; finer-grained |
| 28 | +// than NO_THREAD_SAFETY_ANALYSIS |
| 29 | +# define PUSH_IGNORE_THREAD_SAFETY \ |
| 30 | + _Pragma("GCC diagnostic push") \ |
| 31 | + _Pragma("GCC diagnostic ignored \"-Wthread-safety\"") |
| 32 | +# define POP_THREAD_SAFETY _Pragma("GCC diagnostic pop") |
| 33 | + |
| 34 | +#else |
| 35 | +# define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op |
| 36 | +# define PUSH_IGNORE_THREAD_SAFETY |
| 37 | +# define POP_THREAD_SAFETY |
| 38 | +#endif |
| 39 | + |
| 40 | +// Document if a shared variable/field needs to be protected by a lock. |
| 41 | +// GUARDED_BY allows the user to specify a particular lock that should be |
| 42 | +// held when accessing the annotated variable, while GUARDED_VAR only |
| 43 | +// indicates a shared variable should be guarded (by any lock). GUARDED_VAR |
| 44 | +// is primarily used when the client cannot express the name of the lock. |
| 45 | +#define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) |
| 46 | +#define GUARDED_VAR THREAD_ANNOTATION_ATTRIBUTE__(guarded) |
| 47 | + |
| 48 | +// Document if the memory location pointed to by a pointer should be guarded |
| 49 | +// by a lock when dereferencing the pointer. Similar to GUARDED_VAR, |
| 50 | +// PT_GUARDED_VAR is primarily used when the client cannot express the name |
| 51 | +// of the lock. Note that a pointer variable to a shared memory location |
| 52 | +// could itself be a shared variable. For example, if a shared global pointer |
| 53 | +// q, which is guarded by mu1, points to a shared memory location that is |
| 54 | +// guarded by mu2, q should be annotated as follows: |
| 55 | +// int *q GUARDED_BY(mu1) PT_GUARDED_BY(mu2); |
| 56 | +#define PT_GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) |
| 57 | +#define PT_GUARDED_VAR THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded) |
| 58 | + |
| 59 | +// Document the acquisition order between locks that can be held |
| 60 | +// simultaneously by a thread. For any two locks that need to be annotated |
| 61 | +// to establish an acquisition order, only one of them needs the annotation. |
| 62 | +// (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER |
| 63 | +// and ACQUIRED_BEFORE.) |
| 64 | +#define ACQUIRED_AFTER(...) THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__)) |
| 65 | +#define ACQUIRED_BEFORE(...) THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__)) |
| 66 | + |
| 67 | +// The following three annotations document the lock requirements for |
| 68 | +// functions/methods. |
| 69 | + |
| 70 | +// Document if a function expects certain locks to be held before it is called |
| 71 | +#define REQUIRES(...) \ |
| 72 | + THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__)) |
| 73 | + |
| 74 | +#define REQUIRES_SHARED(...) \ |
| 75 | + THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__)) |
| 76 | + |
| 77 | +// Document the locks acquired in the body of the function. These locks |
| 78 | +// cannot be held when calling this function (as google3's Mutex locks are |
| 79 | +// non-reentrant). |
| 80 | +#define EXCLUDES(x) THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) |
| 81 | + |
| 82 | +// Document the lock the annotated function returns without acquiring it. |
| 83 | +#define RETURN_CAPABILITY(x) THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) |
| 84 | + |
| 85 | +// Document if a class/type is a lockable type (such as the Mutex class). |
| 86 | +#define CAPABILITY THREAD_ANNOTATION_ATTRIBUTE__(lockable) |
| 87 | + |
| 88 | +// Document if a class is a scoped lockable type (such as the MutexLock class). |
| 89 | +#define SCOPED_CAPABILITY THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) |
| 90 | + |
| 91 | +// The following annotations specify lock and unlock primitives. |
| 92 | +#define CAPABILITY_ACQUIRE(...) \ |
| 93 | + THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__)) |
| 94 | + |
| 95 | +#define EXCLUSIVE_RELEASE(...) \ |
| 96 | + THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__)) |
| 97 | + |
| 98 | +#define ACQUIRE_SHARED(...) \ |
| 99 | + THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__)) |
| 100 | + |
| 101 | +#define TRY_ACQUIRE(...) \ |
| 102 | + THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__)) |
| 103 | + |
| 104 | +#define SHARED_TRYLOCK_FUNCTION(...) \ |
| 105 | + THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__)) |
| 106 | + |
| 107 | +#define CAPABILITY_RELEASE(...) THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__)) |
| 108 | + |
| 109 | +// An escape hatch for thread safety analysis to ignore the annotated function. |
| 110 | +#define NO_THREAD_SAFETY_ANALYSIS \ |
| 111 | + THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) |
| 112 | + |
| 113 | +// Newer capabilities |
| 114 | +#define ASSERT_CAPABILITY(x) THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) |
| 115 | + |
| 116 | +#define ASSERT_SHARED_CAPABILITY(x) \ |
| 117 | + THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) |
| 118 | + |
| 119 | +// Additions from current clang assertions. |
| 120 | +// Note: new-style definitions, since these didn't exist in the old style |
| 121 | +#define RELEASE_SHARED(...) \ |
| 122 | + THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__)) |
| 123 | + |
| 124 | +#define RELEASE_GENERIC(...) \ |
| 125 | + THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(__VA_ARGS__)) |
| 126 | + |
| 127 | +// Mozilla additions: |
| 128 | + |
| 129 | +// AutoUnlock is supported by clang currently, but oddly you must use |
| 130 | +// EXCLUSIVE_RELEASE() for both the RAII constructor *and* the destructor. |
| 131 | +// This hides the ugliness until they fix it upstream. |
| 132 | +#define SCOPED_UNLOCK_RELEASE(...) EXCLUSIVE_RELEASE(__VA_ARGS__) |
| 133 | +#define SCOPED_UNLOCK_REACQUIRE(...) EXCLUSIVE_RELEASE(__VA_ARGS__) |
| 134 | + |
| 135 | +#endif /* mozilla_ThreadSafety_h */ |
0 commit comments