mfbt/ThreadSafety.h

   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__) && (__clang_major__ >= 8) && !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_var)
  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_var)
  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(...) \
  65   THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
  66 #define ACQUIRED_BEFORE(...) \
  67   THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
  68
  69 // The following three annotations document the lock requirements for
  70 // functions/methods.
  71
  72 // Document if a function expects certain locks to be held before it is called
  73 #define REQUIRES(...) \
  74   THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
  75
  76 #define REQUIRES_SHARED(...) \
  77   THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
  78
  79 // Document the locks acquired in the body of the function. These locks
  80 // cannot be held when calling this function (as google3's Mutex locks are
  81 // non-reentrant).
  82 #define EXCLUDES(x) THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x))
  83
  84 // Document the lock the annotated function returns without acquiring it.
  85 #define RETURN_CAPABILITY(x) THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
  86
  87 // Document if a class/type is a lockable type (such as the Mutex class).
  88 #define CAPABILITY THREAD_ANNOTATION_ATTRIBUTE__(lockable)
  89
  90 // Document if a class is a scoped lockable type (such as the MutexLock class).
  91 #define SCOPED_CAPABILITY THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
  92
  93 // The following annotations specify lock and unlock primitives.
  94 #define CAPABILITY_ACQUIRE(...) \
  95   THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
  96
  97 #define EXCLUSIVE_RELEASE(...) \
  98   THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))
  99
 100 #define ACQUIRE_SHARED(...) \
 101   THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
 102
 103 #define TRY_ACQUIRE(...) \
 104   THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
 105
 106 #define SHARED_TRYLOCK_FUNCTION(...) \
 107   THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
 108
 109 #define CAPABILITY_RELEASE(...) \
 110   THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
 111
 112 // An escape hatch for thread safety analysis to ignore the annotated function.
 113 #define NO_THREAD_SAFETY_ANALYSIS \
 114   THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
 115
 116 // Newer capabilities
 117 #define ASSERT_CAPABILITY(x) THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))
 118
 119 #define ASSERT_SHARED_CAPABILITY(x) \
 120   THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))
 121
 122 // Additions from current clang assertions.
 123 // Note: new-style definitions, since these didn't exist in the old style
 124 #define RELEASE_SHARED(...) \
 125   THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))
 126
 127 #define RELEASE_GENERIC(...) \
 128   THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(__VA_ARGS__))
 129
 130 // Mozilla additions:
 131
 132 // AutoUnlock is supported by clang currently, but oddly you must use
 133 // EXCLUSIVE_RELEASE() for both the RAII constructor *and* the destructor.
 134 // This hides the ugliness until they fix it upstream.
 135 #define SCOPED_UNLOCK_RELEASE(...) EXCLUSIVE_RELEASE(__VA_ARGS__)
 136 #define SCOPED_UNLOCK_REACQUIRE(...) EXCLUSIVE_RELEASE(__VA_ARGS__)
 137
 138 #endif /* mozilla_ThreadSafety_h */