pw_sync/public/pw_sync/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"

/// @def PW_GUARDED_BY
///
/// Documents if a shared field or global variable needs to be protected by a
/// lock. `PW_GUARDED_BY()` allows the user to specify a particular lock that
/// should be held when accessing the annotated variable.
///
/// Although this annotation (and `PW_PT_GUARDED_BY()`, below) cannot be applied
/// to local variables, a local variable and its associated lock can often be
/// combined into a small class or struct, thereby allowing the annotation.
///
/// Example:
///
/// @code
///    class Foo {
///      Mutex mu_;
///      int p1_ PW_GUARDED_BY(mu_);
///      ...
///    };
/// @endcode
///
#if PW_HAVE_ATTRIBUTE(guarded_by)
#define PW_GUARDED_BY(x) __attribute__((guarded_by(x)))
#else
#define PW_GUARDED_BY(x)
#endif

/// @def PW_PT_GUARDED_BY
///
/// Documents if the memory location pointed to by a pointer should be guarded
/// by a lock when dereferencing the pointer.
///
/// Example:
///
/// @code
///    class Foo {
///      Mutex mu_;
///      int *p1_ PW_PT_GUARDED_BY(mu_);
///      ...
///    };
/// @endcode
///
/// @note A pointer variable to a shared memory location could itself be a
/// shared variable.
///
/// Example:
///
/// @code
///    // `q_`, guarded by `mu1_`, points to a shared memory location that is
///    // guarded by `mu2_`:
///    int *q_ PW_GUARDED_BY(mu1_) PW_PT_GUARDED_BY(mu2_);
/// @endcode
#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

/// @def PW_ACQUIRED_AFTER
/// @def PW_ACQUIRED_BEFORE
///
/// Documents the acquisition order between locks that can be held
/// simultaneously by a thread. For any two locks that need to be annotated
/// to establish an acquisition order, only one of them needs the annotation.
/// (i.e. You don't have to annotate both locks with both `PW_ACQUIRED_AFTER()`
/// and `PW_ACQUIRED_BEFORE()`.)
///
/// As with `PW_GUARDED_BY()`, this is only applicable to locks that are shared
/// fields or global variables.
///
/// Example:
///
/// @code
///   Mutex m1_;
///   Mutex m2_ PW_ACQUIRED_AFTER(m1_);
/// @endcode
#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

/// @def PW_EXCLUSIVE_LOCKS_REQUIRED
/// @def PW_SHARED_LOCKS_REQUIRED
///
/// Documents a function that expects a lock to be held prior to entry.
/// The lock is expected to be held both on entry to, and exit from, the
/// function.
///
/// An exclusive lock allows read-write access to the guarded data member(s),
/// and only one thread can acquire a lock exclusively at any one time. A shared
/// lock allows read-only access, and any number of threads can acquire a shared
/// lock concurrently.
///
/// Generally, non-const methods should be annotated with
/// `PW_EXCLUSIVE_LOCKS_REQUIRED()`, while const methods should be annotated
/// with `PW_SHARED_LOCKS_REQUIRED()`.
///
/// Example:
///
/// @code
///   Mutex mu1, mu2;
///   int a PW_GUARDED_BY(mu1);
///   int b PW_GUARDED_BY(mu2);
///
///   void foo() PW_EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { ... }
///   void bar() const PW_SHARED_LOCKS_REQUIRED(mu1, mu2) { ... }
/// @endcode
#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

/// @def PW_LOCKS_EXCLUDED
///
/// Documents that the caller must not hold the given lock. This annotation is
/// often used to prevent deadlocks. Pigweed's mutex implementation is not
/// re-entrant, so a deadlock will occur if the function acquires the mutex a
/// second time.
///
/// Example:
///
/// @code
///   Mutex mu;
///   int a PW_GUARDED_BY(mu);
///
///   void foo() PW_LOCKS_EXCLUDED(mu) {
///     mu.lock();
///     ...
///     mu.unlock();
///   }
/// @endcode
#if PW_HAVE_ATTRIBUTE(locks_excluded)
#define PW_LOCKS_EXCLUDED(...) __attribute__((locks_excluded(__VA_ARGS__)))
#else
#define PW_LOCKS_EXCLUDED(...)
#endif

/// @def PW_LOCK_RETURNED
///
/// Documents a function that returns a lock without acquiring it.  For example,
/// a public getter method that returns a pointer to a private lock should
/// be annotated with `PW_LOCK_RETURNED()`.
///
/// Example:
///
/// @code
///   class Foo {
///    public:
///     Mutex* mu() PW_LOCK_RETURNED(mu) { return μ }
///
///    private:
///     Mutex mu;
///   };
/// @endcode
#if PW_HAVE_ATTRIBUTE(lock_returned)
#define PW_LOCK_RETURNED(x) __attribute__((lock_returned(x)))
#else
#define PW_LOCK_RETURNED(x)
#endif

/// @def PW_LOCKABLE
///
/// Documents if a class/type is a lockable type (such as the `pw::sync::Mutex`
/// class). The name is used in the warning messages. This can also be useful on
/// classes which have locking like semantics but aren't actually locks.
#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

/// @def PW_SCOPED_LOCKABLE
///
/// Documents if a class does RAII locking. The name is used in the warning
/// messages.
///
/// The constructor should use `LOCK_FUNCTION()` to specify the lock that is
/// acquired, and the destructor should use `UNLOCK_FUNCTION()` with no
/// arguments; the analysis will assume that the destructor unlocks whatever the
/// constructor locked.
#if PW_HAVE_ATTRIBUTE(scoped_lockable)
#define PW_SCOPED_LOCKABLE __attribute__((scoped_lockable))
#else
#define PW_SCOPED_LOCKABLE
#endif

/// @def PW_EXCLUSIVE_LOCK_FUNCTION
///
/// Documents functions that acquire a lock in the body of a function, and do
/// not release it.
#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

/// @def PW_SHARED_LOCK_FUNCTION
///
/// Documents functions that acquire a shared (reader) lock in the body of a
/// function, and do not release it.
#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

/// @def PW_UNLOCK_FUNCTION
///
/// Documents functions that expect a lock to be held on entry to the function,
/// and release it in the body of the function.
#if PW_HAVE_ATTRIBUTE(unlock_function)
#define PW_UNLOCK_FUNCTION(...) __attribute__((unlock_function(__VA_ARGS__)))
#else
#define PW_UNLOCK_FUNCTION(...)
#endif

/// @def PW_EXCLUSIVE_TRYLOCK_FUNCTION
/// @def PW_SHARED_TRYLOCK_FUNCTION
///
/// Documents functions that try to acquire a lock, and return success or
/// failure (or a non-boolean value that can be interpreted as a boolean). The
/// first argument should be `true` for functions that return `true` on success,
/// or `false` for functions that return `false` on success. The second argument
/// specifies the lock that is locked on success. If unspecified, this lock is
/// assumed to be `this`.
#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

/// @def PW_ASSERT_EXCLUSIVE_LOCK
/// @def PW_ASSERT_SHARED_LOCK
///
/// Documents functions that dynamically check to see if a lock is held, and
/// fail if it is not held.
#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

/// @def PW_NO_LOCK_SAFETY_ANALYSIS
///
/// Turns off thread safety checking within the body of a particular function.
/// This annotation is used to mark functions that are known to be correct, but
/// the locking behavior is more complicated than the analyzer can handle.
#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