| 1 |
// -*- Mode: C++; c-basic-offset: 2; indent-tabs-mode: nil -*- |
| 2 |
// Copyright (c) 2008, Google Inc. |
| 3 |
// All rights reserved. |
| 4 |
// |
| 5 |
// Redistribution and use in source and binary forms, with or without |
| 6 |
// modification, are permitted provided that the following conditions are |
| 7 |
// met: |
| 8 |
// |
| 9 |
// * Redistributions of source code must retain the above copyright |
| 10 |
// notice, this list of conditions and the following disclaimer. |
| 11 |
// * Redistributions in binary form must reproduce the above |
| 12 |
// copyright notice, this list of conditions and the following disclaimer |
| 13 |
// in the documentation and/or other materials provided with the |
| 14 |
// distribution. |
| 15 |
// * Neither the name of Google Inc. nor the names of its |
| 16 |
// contributors may be used to endorse or promote products derived from |
| 17 |
// this software without specific prior written permission. |
| 18 |
// |
| 19 |
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 20 |
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 21 |
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 22 |
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 23 |
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 24 |
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 25 |
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 26 |
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 27 |
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 28 |
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 29 |
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 30 |
|
| 31 |
// --- |
| 32 |
// Author: Le-Chun Wu |
| 33 |
// |
| 34 |
// This header file contains the macro definitions for thread safety |
| 35 |
// annotations that allow the developers to document the locking policies |
| 36 |
// of their multi-threaded code. The annotations can also help program |
| 37 |
// analysis tools to identify potential thread safety issues. |
| 38 |
// |
| 39 |
// The annotations are implemented using clang's "attributes" extension. |
| 40 |
// Using the macros defined here instead of the raw clang attributes allows |
| 41 |
// for portability and future compatibility. |
| 42 |
// |
| 43 |
// This functionality is not yet fully implemented in perftools, |
| 44 |
// but may be one day. |
| 45 |
|
| 46 |
#ifndef BASE_THREAD_ANNOTATIONS_H_ |
| 47 |
#define BASE_THREAD_ANNOTATIONS_H_ |
| 48 |
|
| 49 |
|
| 50 |
#if defined(__clang__) |
| 51 |
#define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) |
| 52 |
#else |
| 53 |
#define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op |
| 54 |
#endif |
| 55 |
|
| 56 |
|
| 57 |
// Document if a shared variable/field needs to be protected by a lock. |
| 58 |
// GUARDED_BY allows the user to specify a particular lock that should be |
| 59 |
// held when accessing the annotated variable, while GUARDED_VAR only |
| 60 |
// indicates a shared variable should be guarded (by any lock). GUARDED_VAR |
| 61 |
// is primarily used when the client cannot express the name of the lock. |
| 62 |
#define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) |
| 63 |
#define GUARDED_VAR THREAD_ANNOTATION_ATTRIBUTE__(guarded) |
| 64 |
|
| 65 |
// Document if the memory location pointed to by a pointer should be guarded |
| 66 |
// by a lock when dereferencing the pointer. Similar to GUARDED_VAR, |
| 67 |
// PT_GUARDED_VAR is primarily used when the client cannot express the name |
| 68 |
// of the lock. Note that a pointer variable to a shared memory location |
| 69 |
// could itself be a shared variable. For example, if a shared global pointer |
| 70 |
// q, which is guarded by mu1, points to a shared memory location that is |
| 71 |
// guarded by mu2, q should be annotated as follows: |
| 72 |
// int *q GUARDED_BY(mu1) PT_GUARDED_BY(mu2); |
| 73 |
#define PT_GUARDED_BY(x) \ |
| 74 |
THREAD_ANNOTATION_ATTRIBUTE__(point_to_guarded_by(x)) |
| 75 |
#define PT_GUARDED_VAR \ |
| 76 |
THREAD_ANNOTATION_ATTRIBUTE__(point_to_guarded) |
| 77 |
|
| 78 |
// Document the acquisition order between locks that can be held |
| 79 |
// simultaneously by a thread. For any two locks that need to be annotated |
| 80 |
// to establish an acquisition order, only one of them needs the annotation. |
| 81 |
// (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER |
| 82 |
// and ACQUIRED_BEFORE.) |
| 83 |
#define ACQUIRED_AFTER(x) \ |
| 84 |
THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) |
| 85 |
#define ACQUIRED_BEFORE(x) \ |
| 86 |
THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) |
| 87 |
|
| 88 |
// The following three annotations document the lock requirements for |
| 89 |
// functions/methods. |
| 90 |
|
| 91 |
// Document if a function expects certain locks to be held before it is called |
| 92 |
#define EXCLUSIVE_LOCKS_REQUIRED(x) \ |
| 93 |
THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(x)) |
| 94 |
|
| 95 |
#define SHARED_LOCKS_REQUIRED(x) \ |
| 96 |
THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(x)) |
| 97 |
|
| 98 |
// Document the locks acquired in the body of the function. These locks |
| 99 |
// cannot be held when calling this function (as google3's Mutex locks are |
| 100 |
// non-reentrant). |
| 101 |
#define LOCKS_EXCLUDED(x) \ |
| 102 |
THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) |
| 103 |
|
| 104 |
// Document the lock the annotated function returns without acquiring it. |
| 105 |
#define LOCK_RETURNED(x) THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) |
| 106 |
|
| 107 |
// Document if a class/type is a lockable type (such as the Mutex class). |
| 108 |
#define LOCKABLE THREAD_ANNOTATION_ATTRIBUTE__(lockable) |
| 109 |
|
| 110 |
// Document if a class is a scoped lockable type (such as the MutexLock class). |
| 111 |
#define SCOPED_LOCKABLE THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) |
| 112 |
|
| 113 |
// The following annotations specify lock and unlock primitives. |
| 114 |
#define EXCLUSIVE_LOCK_FUNCTION(x) \ |
| 115 |
THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(x)) |
| 116 |
|
| 117 |
#define SHARED_LOCK_FUNCTION(x) \ |
| 118 |
THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(x)) |
| 119 |
|
| 120 |
#define EXCLUSIVE_TRYLOCK_FUNCTION(x) \ |
| 121 |
THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(x)) |
| 122 |
|
| 123 |
#define SHARED_TRYLOCK_FUNCTION(x) \ |
| 124 |
THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(x)) |
| 125 |
|
| 126 |
#define UNLOCK_FUNCTION(x) \ |
| 127 |
THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(x)) |
| 128 |
|
| 129 |
// An escape hatch for thread safety analysis to ignore the annotated function. |
| 130 |
#define NO_THREAD_SAFETY_ANALYSIS \ |
| 131 |
THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) |
| 132 |
|
| 133 |
#endif // BASE_THREAD_ANNOTATIONS_H_ |