15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2008, Google Inc. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// All rights reserved. 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Redistribution and use in source and binary forms, with or without 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// modification, are permitted provided that the following conditions are 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// met: 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// * Redistributions of source code must retain the above copyright 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// notice, this list of conditions and the following disclaimer. 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// * Redistributions in binary form must reproduce the above 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// copyright notice, this list of conditions and the following disclaimer 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// in the documentation and/or other materials provided with the 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// distribution. 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// * Neither the name of Google Inc. nor the names of its 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// contributors may be used to endorse or promote products derived from 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// this software without specific prior written permission. 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// --- 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Author: Le-Chun Wu 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This header file contains the macro definitions for thread safety 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// annotations that allow the developers to document the locking policies 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// of their multi-threaded code. The annotations can also help program 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// analysis tools to identify potential thread safety issues. 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The annotations are implemented using GCC's "attributes" extension. 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Using the macros defined here instead of the raw GCC attributes allows 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// for portability and future compatibility. 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This functionality is not yet fully implemented in perftools, 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// but may be one day. 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef BASE_THREAD_ANNOTATIONS_H_ 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define BASE_THREAD_ANNOTATIONS_H_ 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(__GNUC__) \ 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) \ 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) && defined(__SUPPORT_TS_ANNOTATION__) && (!defined(SWIG)) 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Document if a shared variable/field needs to be protected by a lock. 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// GUARDED_BY allows the user to specify a particular lock that should be 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// held when accessing the annotated variable, while GUARDED_VAR only 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// indicates a shared variable should be guarded (by any lock). GUARDED_VAR 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// is primarily used when the client cannot express the name of the lock. 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define GUARDED_VAR THREAD_ANNOTATION_ATTRIBUTE__(guarded) 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Document if the memory location pointed to by a pointer should be guarded 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// by a lock when dereferencing the pointer. Similar to GUARDED_VAR, 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// PT_GUARDED_VAR is primarily used when the client cannot express the name 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// of the lock. Note that a pointer variable to a shared memory location 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// could itself be a shared variable. For example, if a shared global pointer 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// q, which is guarded by mu1, points to a shared memory location that is 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// guarded by mu2, q should be annotated as follows: 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// int *q GUARDED_BY(mu1) PT_GUARDED_BY(mu2); 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PT_GUARDED_BY(x) \ 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(point_to_guarded_by(x)) 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PT_GUARDED_VAR \ 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(point_to_guarded) 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Document the acquisition order between locks that can be held 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// simultaneously by a thread. For any two locks that need to be annotated 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// to establish an acquisition order, only one of them needs the annotation. 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// and ACQUIRED_BEFORE.) 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define ACQUIRED_AFTER(x) \ 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define ACQUIRED_BEFORE(x) \ 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The following three annotations document the lock requirements for 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// functions/methods. 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Document if a function expects certain locks to be held before it is called 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define EXCLUSIVE_LOCKS_REQUIRED(x) \ 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(x)) 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define SHARED_LOCKS_REQUIRED(x) \ 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(x)) 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Document the locks acquired in the body of the function. These locks 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// cannot be held when calling this function (as google3's Mutex locks are 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// non-reentrant). 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define LOCKS_EXCLUDED(x) \ 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Document the lock the annotated function returns without acquiring it. 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define LOCK_RETURNED(x) THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Document if a class/type is a lockable type (such as the Mutex class). 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define LOCKABLE THREAD_ANNOTATION_ATTRIBUTE__(lockable) 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Document if a class is a scoped lockable type (such as the MutexLock class). 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define SCOPED_LOCKABLE THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The following annotations specify lock and unlock primitives. 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define EXCLUSIVE_LOCK_FUNCTION(x) \ 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock(x)) 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define SHARED_LOCK_FUNCTION(x) \ 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(shared_lock(x)) 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define EXCLUSIVE_TRYLOCK_FUNCTION(x) \ 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock(x)) 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define SHARED_TRYLOCK_FUNCTION(x) \ 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock(x)) 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define UNLOCK_FUNCTION(x) \ 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(unlock(x)) 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// An escape hatch for thread safety analysis to ignore the annotated function. 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define NO_THREAD_SAFETY_ANALYSIS \ 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // BASE_THREAD_ANNOTATIONS_H_ 135