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 MOZ_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
  27 // Allow for localized suppression of thread-safety warnings; finer-grained
  28 // than MOZ_NO_THREAD_SAFETY_ANALYSIS
  29 #  define MOZ_PUSH_IGNORE_THREAD_SAFETY \
  30     _Pragma("GCC diagnostic push")      \
  31         _Pragma("GCC diagnostic ignored \"-Wthread-safety\"")
  32 #  define MOZ_POP_THREAD_SAFETY _Pragma("GCC diagnostic pop")
  33
  34 #else
  35 #  define MOZ_THREAD_ANNOTATION_ATTRIBUTE__(x)  // no-op
  36 #  define MOZ_PUSH_IGNORE_THREAD_SAFETY
  37 #  define MOZ_POP_THREAD_SAFETY
  38 #endif
  39
  40 // Document if a shared variable/field needs to be protected by a lock.
  41 // MOZ_GUARDED_BY allows the user to specify a particular lock that should be
  42 // held when accessing the annotated variable, while MOZ_GUARDED_VAR only
  43 // indicates a shared variable should be guarded (by any lock). MOZ_GUARDED_VAR
  44 // is primarily used when the client cannot express the name of the lock.
  45 #define MOZ_GUARDED_BY(x) MOZ_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
  46 #define MOZ_GUARDED_VAR MOZ_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 MOZ_GUARDED_VAR,
  50 // MOZ_PT_GUARDED_VAR is primarily used when the client cannot express the
  51 // name 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 MOZ_GUARDED_BY(mu1) MOZ_PT_GUARDED_BY(mu2);
  56 #define MOZ_PT_GUARDED_BY(x) MOZ_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
  57 #define MOZ_PT_GUARDED_VAR MOZ_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 MOZ_ACQUIRED_AFTER
  63 // and MOZ_ACQUIRED_BEFORE.)
  64 #define MOZ_ACQUIRED_AFTER(...) \
  65   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
  66 #define MOZ_ACQUIRED_BEFORE(...) \
  67   MOZ_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 MOZ_REQUIRES(...) \
  74   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
  75
  76 #define MOZ_REQUIRES_SHARED(...) \
  77   MOZ_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 MOZ_EXCLUDES(x) MOZ_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x))
  83
  84 // Document the lock the annotated function returns without acquiring it.
  85 #define MOZ_RETURN_CAPABILITY(x) \
  86   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
  87
  88 // Document if a class/type is a lockable type (such as the Mutex class).
  89 #define MOZ_CAPABILITY(x) MOZ_THREAD_ANNOTATION_ATTRIBUTE__(capability(x))
  90
  91 // Document if a class is a scoped lockable type (such as the MutexLock class).
  92 #define MOZ_SCOPED_CAPABILITY MOZ_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
  93
  94 // The following annotations specify lock and unlock primitives.
  95 #define MOZ_CAPABILITY_ACQUIRE(...) \
  96   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
  97
  98 #define MOZ_EXCLUSIVE_RELEASE(...) \
  99   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))
 100
 101 #define MOZ_ACQUIRE_SHARED(...) \
 102   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
 103
 104 #define MOZ_TRY_ACQUIRE(...) \
 105   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
 106
 107 #define MOZ_SHARED_TRYLOCK_FUNCTION(...) \
 108   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
 109
 110 #define MOZ_CAPABILITY_RELEASE(...) \
 111   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
 112
 113 // An escape hatch for thread safety analysis to ignore the annotated function.
 114 #define MOZ_NO_THREAD_SAFETY_ANALYSIS \
 115   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
 116
 117 // Newer capabilities
 118 #define MOZ_ASSERT_CAPABILITY(x) \
 119   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))
 120
 121 #define MOZ_ASSERT_SHARED_CAPABILITY(x) \
 122   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))
 123
 124 // Additions from current clang assertions.
 125 // Note: new-style definitions, since these didn't exist in the old style
 126 #define MOZ_RELEASE_SHARED(...) \
 127   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))
 128
 129 #define MOZ_RELEASE_GENERIC(...) \
 130   MOZ_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(__VA_ARGS__))
 131
 132 // Mozilla additions:
 133
 134 // AutoUnlock is supported by clang currently, but oddly you must use
 135 // MOZ_EXCLUSIVE_RELEASE() for both the RAII constructor *and* the destructor.
 136 // This hides the ugliness until they fix it upstream.
 137 #define MOZ_SCOPED_UNLOCK_RELEASE(...) MOZ_EXCLUSIVE_RELEASE(__VA_ARGS__)
 138 #define MOZ_SCOPED_UNLOCK_REACQUIRE(...) MOZ_EXCLUSIVE_RELEASE(__VA_ARGS__)
 139
 140 #endif /* mozilla_ThreadSafety_h */