lock_annotations.h

// Copyright 2021 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
//
// This header file contains macro definitions for thread safety annotations
// that allow developers to document the locking policies of multi-threaded
// code. The annotations can also help program analysis tools to identify
// potential thread safety issues.
//
// These annotations are implemented using compiler attributes. Using the macros
// defined here instead of raw attributes allow for portability and future
// compatibility.
//
// The thread safety analysis system is documented at
// http://clang.llvm.org/docs/ThreadSafetyAnalysis.html
//
// When referring to locks in the arguments of the attributes, you should
// use variable names or more complex expressions (e.g. my_object->lock_)
// that evaluate to a concrete lock object whenever possible. If the lock
// you want to refer to is not in scope, you may use a member pointer
// (e.g. &MyClass::lock_) to refer to a lock in some (unknown) object.
 
#pragma once
 
#include "pw_preprocessor/compiler.h"
 
#if PW_HAVE_ATTRIBUTE(guarded_by)
#define PW_GUARDED_BY(x) __attribute__((guarded_by(x)))
#else
#define PW_GUARDED_BY(x)
#endif
 
#if PW_HAVE_ATTRIBUTE(pt_guarded_by)
#define PW_PT_GUARDED_BY(x) __attribute__((pt_guarded_by(x)))
#else
#define PW_PT_GUARDED_BY(x)
#endif
 
#if PW_HAVE_ATTRIBUTE(acquired_after)
#define PW_ACQUIRED_AFTER(...) __attribute__((acquired_after(__VA_ARGS__)))
#else
#define PW_ACQUIRED_AFTER(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(acquired_before)
#define PW_ACQUIRED_BEFORE(...) __attribute__((acquired_before(__VA_ARGS__)))
#else
#define PW_ACQUIRED_BEFORE(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(exclusive_locks_required)
#define PW_EXCLUSIVE_LOCKS_REQUIRED(...) \
  __attribute__((exclusive_locks_required(__VA_ARGS__)))
#else
#define PW_EXCLUSIVE_LOCKS_REQUIRED(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(shared_locks_required)
#define PW_SHARED_LOCKS_REQUIRED(...) \
  __attribute__((shared_locks_required(__VA_ARGS__)))
#else
#define PW_SHARED_LOCKS_REQUIRED(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(locks_excluded)
#define PW_LOCKS_EXCLUDED(...) __attribute__((locks_excluded(__VA_ARGS__)))
#else
#define PW_LOCKS_EXCLUDED(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(lock_returned)
#define PW_LOCK_RETURNED(x) __attribute__((lock_returned(x)))
#else
#define PW_LOCK_RETURNED(x)
#endif
 
#if PW_HAVE_ATTRIBUTE(capability)
#define PW_LOCKABLE(name) __attribute__((capability(name)))
#elif PW_HAVE_ATTRIBUTE(lockable)
#define PW_LOCKABLE(name) __attribute__((lockable))
#else
#define PW_LOCKABLE(name)
#endif
 
#if PW_HAVE_ATTRIBUTE(scoped_lockable)
#define PW_SCOPED_LOCKABLE __attribute__((scoped_lockable))
#else
#define PW_SCOPED_LOCKABLE
#endif
 
#if PW_HAVE_ATTRIBUTE(exclusive_lock_function)
#define PW_EXCLUSIVE_LOCK_FUNCTION(...) \
  __attribute__((exclusive_lock_function(__VA_ARGS__)))
#else
#define PW_EXCLUSIVE_LOCK_FUNCTION(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(shared_lock_function)
#define PW_SHARED_LOCK_FUNCTION(...) \
  __attribute__((shared_lock_function(__VA_ARGS__)))
#else
#define PW_SHARED_LOCK_FUNCTION(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(unlock_function)
#define PW_UNLOCK_FUNCTION(...) __attribute__((unlock_function(__VA_ARGS__)))
#else
#define PW_UNLOCK_FUNCTION(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(exclusive_trylock_function)
#define PW_EXCLUSIVE_TRYLOCK_FUNCTION(...) \
  __attribute__((exclusive_trylock_function(__VA_ARGS__)))
#else
#define PW_EXCLUSIVE_TRYLOCK_FUNCTION(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(shared_trylock_function)
#define PW_SHARED_TRYLOCK_FUNCTION(...) \
  __attribute__((shared_trylock_function(__VA_ARGS__)))
#else
#define PW_SHARED_TRYLOCK_FUNCTION(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(assert_exclusive_lock)
#define PW_ASSERT_EXCLUSIVE_LOCK(...) \
  __attribute__((assert_exclusive_lock(__VA_ARGS__)))
#else
#define PW_ASSERT_EXCLUSIVE_LOCK(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(assert_shared_lock)
#define PW_ASSERT_SHARED_LOCK(...) \
  __attribute__((assert_shared_lock(__VA_ARGS__)))
#else
#define PW_ASSERT_SHARED_LOCK(...)
#endif
 
#if PW_HAVE_ATTRIBUTE(no_thread_safety_analysis)
#define PW_NO_LOCK_SAFETY_ANALYSIS __attribute__((no_thread_safety_analysis))
#else
#define PW_NO_LOCK_SAFETY_ANALYSIS
#endif