pw_sync

Oveview

Main docs: Home

Classes
class	pw::sync::BinarySemaphore
class	pw::sync::BorrowedPointer< GuardedType, LockType >
class	pw::sync::Borrowable< GuardedType, LockType >
class	pw::sync::CountingSemaphore
class	pw::sync::InlineBorrowable< GuardedType, Lock, LockInterface >
class	pw::sync::InterruptSpinLock
class	pw::sync::VirtualInterruptSpinLock
struct	pw::sync::is_basic_lockable< Lock, typename >
struct	pw::sync::is_basic_lockable< Lock, std::void_t< decltype(std::declval< Lock >().lock()), decltype(std::declval< Lock >().unlock())> >
struct	pw::sync::is_lockable< Lock, typename >
struct	pw::sync::is_lockable< Lock, std::void_t< decltype(std::declval< Lock >().try_lock())> >
struct	pw::sync::is_lockable_for< Lock, Duration, typename >
struct	pw::sync::is_lockable_for< Lock, Duration, std::void_t< decltype(std::declval< Lock >().try_lock_for(std::declval< Duration >()))> >
struct	pw::sync::is_lockable_until< Lock, TimePoint, typename >
struct	pw::sync::is_lockable_until< Lock, TimePoint, std::void_t< decltype(std::declval< Lock >().try_lock_until(std::declval< TimePoint >()))> >
struct	pw::sync::is_timed_lockable< Lock, Clock >
class	pw::sync::Mutex
class	pw::sync::VirtualMutex
class	pw::sync::NoLock
class	pw::sync::ThreadNotification
class	pw::sync::TimedBorrowable< GuardedType, LockType >
class	pw::sync::TimedMutex
class	pw::sync::VirtualTimedMutex
class	pw::sync::TimedThreadNotification
class	pw::sync::VirtualBasicLockable
class	pw::sync::NoOpLock
class	pw::sync::GenericBasicLockable< LockType >
class	pw::sync::GenericLockable< LockType >

Macros
#define	PW_GUARDED_BY(x)
#define	PW_PT_GUARDED_BY(x)
#define	PW_ACQUIRED_AFTER(...)
#define	PW_ACQUIRED_BEFORE(...)
#define	PW_EXCLUSIVE_LOCKS_REQUIRED(...)
#define	PW_SHARED_LOCKS_REQUIRED(...)
#define	PW_LOCKS_EXCLUDED(...)
#define	PW_LOCK_RETURNED(x)
#define	PW_LOCKABLE(name)
#define	PW_SCOPED_LOCKABLE
#define	PW_EXCLUSIVE_LOCK_FUNCTION(...)
#define	PW_SHARED_LOCK_FUNCTION(...)
#define	PW_UNLOCK_FUNCTION(...)
#define	PW_EXCLUSIVE_TRYLOCK_FUNCTION(...)
#define	PW_SHARED_TRYLOCK_FUNCTION(...)
#define	PW_ASSERT_EXCLUSIVE_LOCK(...)
#define	PW_ASSERT_SHARED_LOCK(...)
#define	PW_NO_LOCK_SAFETY_ANALYSIS

Typedefs
template<bool kEnableLocking, typename LockType >
using	pw::sync::MaybeLock = std::conditional_t< kEnableLocking, LockType, NoLock >

Functions
void	pw_sync_InterruptSpinLock_Lock (pw_sync_InterruptSpinLock *spin_lock)
bool	pw_sync_InterruptSpinLock_TryLock (pw_sync_InterruptSpinLock *spin_lock)
void	pw_sync_InterruptSpinLock_Unlock (pw_sync_InterruptSpinLock *spin_lock)
void	pw_sync_Mutex_Lock (pw_sync_Mutex *mutex)
	Invokes the Mutex::lock member function on the given mutex.
bool	pw_sync_Mutex_TryLock (pw_sync_Mutex *mutex)
	Invokes the Mutex::try_lock member function on the given mutex.
void	pw_sync_Mutex_Unlock (pw_sync_Mutex *mutex)
	Invokes the Mutex::unlock member function on the given mutex.
void	pw_sync_TimedMutex_Lock (pw_sync_TimedMutex *mutex)
	Invokes the TimedMutex::lock member function on the given mutex.
bool	pw_sync_TimedMutex_TryLock (pw_sync_TimedMutex *mutex)
	Invokes the TimedMutex::try_lock member function on the given mutex.
bool	pw_sync_TimedMutex_TryLockFor (pw_sync_TimedMutex *mutex, pw_chrono_SystemClock_Duration timeout)
	Invokes the TimedMutex::try_lock_for member function on the given mutex.
bool	pw_sync_TimedMutex_TryLockUntil (pw_sync_TimedMutex *mutex, pw_chrono_SystemClock_TimePoint deadline)
void	pw_sync_TimedMutex_Unlock (pw_sync_TimedMutex *mutex)
	Invokes the TimedMutex::unlock member function on the given mutex.

Variables
template<typename Lock >
constexpr bool	pw::sync::is_basic_lockable_v = is_basic_lockable<Lock>::value
	Helper variable template for is_basic_lockable<Lock>::value.
template<typename Lock >
constexpr bool	pw::sync::is_lockable_v = is_lockable<Lock>::value
	Helper variable template for is_lockable<Lock>::value.
template<typename Lock , typename Duration >
constexpr bool	pw::sync::is_lockable_for_v
	Helper variable template for is_lockable_for<Lock, Duration>::value.
template<typename Lock , typename TimePoint >
constexpr bool	pw::sync::is_lockable_until_v
	Helper variable template for is_lockable_until<Lock, TimePoint>::value.
template<typename Lock , typename Clock >
constexpr bool	pw::sync::is_timed_lockable_v
	Helper variable template for is_timed_lockable<Lock, Clock>::value.

Macro Definition Documentation

PW_ACQUIRED_AFTER

#define PW_ACQUIRED_AFTER

(

...

)

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:

Mutex m1_;
Mutex m2_ PW_ACQUIRED_AFTER(m1_);

PW_ASSERT_EXCLUSIVE_LOCK

#define PW_ASSERT_EXCLUSIVE_LOCK

(

...

)

Documents functions that dynamically check to see if a lock is held, and fail if it is not held.

PW_EXCLUSIVE_LOCK_FUNCTION

#define PW_EXCLUSIVE_LOCK_FUNCTION

(

...

)

Documents functions that acquire a lock in the body of a function, and do not release it.

PW_EXCLUSIVE_LOCKS_REQUIRED

#define PW_EXCLUSIVE_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:

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) { ... }

PW_EXCLUSIVE_TRYLOCK_FUNCTION

#define PW_EXCLUSIVE_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.

PW_GUARDED_BY

#define PW_GUARDED_BY

(

x

)

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:

class Foo {
  Mutex mu_;
  int p1_ PW_GUARDED_BY(mu_);
  ...
};

PW_LOCK_RETURNED

#define PW_LOCK_RETURNED

(

x

)

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:

class Foo {
 public:
  Mutex* mu() PW_LOCK_RETURNED(mu) { return μ }
 
 private:
  Mutex mu;
};

PW_LOCKABLE

#define PW_LOCKABLE

(

name

)

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.

PW_LOCKS_EXCLUDED

#define 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:

Mutex mu;
int a PW_GUARDED_BY(mu);
 
void foo() PW_LOCKS_EXCLUDED(mu) {
  mu.lock();
  ...
  mu.unlock();
}

PW_NO_LOCK_SAFETY_ANALYSIS

#define 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.

PW_PT_GUARDED_BY

#define PW_PT_GUARDED_BY

(

x

)

Documents if the memory location pointed to by a pointer should be guarded by a lock when dereferencing the pointer.

Example:

class Foo {
  Mutex mu_;
  int *p1_ PW_PT_GUARDED_BY(mu_);
  ...
};

Note

A pointer variable to a shared memory location could itself be a shared variable.

Example:

// `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_);

PW_SCOPED_LOCKABLE

#define 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.

PW_SHARED_LOCK_FUNCTION

#define PW_SHARED_LOCK_FUNCTION

(

...

)

Documents functions that acquire a shared (reader) lock in the body of a function, and do not release it.

PW_UNLOCK_FUNCTION

#define 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.

Typedef Documentation

MaybeLock

template<bool kEnableLocking, typename LockType >

using pw::sync::MaybeLock = typedef std::conditional_t<kEnableLocking, LockType, NoLock>

MaybeLock is a helper that selects between a real lock type and NoLock based on a boolean template parameter.

Template Parameters

kEnableLocking	If true, MaybeLock is an alias for LockType. If false, MaybeLock is an alias for NoLock.
LockType	The lock type to use when locking is enabled.

Function Documentation

pw_sync_InterruptSpinLock_Lock()

void pw_sync_InterruptSpinLock_Lock

(

pw_sync_InterruptSpinLock *

spin_lock

)

Invokes the InterruptSpinLock::lock member function on the given interrupt_spin_lock.

pw_sync_InterruptSpinLock_TryLock()

bool pw_sync_InterruptSpinLock_TryLock

(

pw_sync_InterruptSpinLock *

spin_lock

)

Invokes the InterruptSpinLock::try_lock member function on the given interrupt_spin_lock.

pw_sync_InterruptSpinLock_Unlock()

void pw_sync_InterruptSpinLock_Unlock

(

pw_sync_InterruptSpinLock *

spin_lock

)

Invokes the InterruptSpinLock::unlock member function on the given interrupt_spin_lock.

pw_sync_TimedMutex_TryLockUntil()

bool pw_sync_TimedMutex_TryLockUntil	(	pw_sync_TimedMutex *	mutex,
		pw_chrono_SystemClock_TimePoint	deadline
	)

Invokes the TimedMutex::try_lock_until member function on the given mutex.

Variable Documentation

is_lockable_for_v

template<typename Lock , typename Duration >

constexpr bool pw::sync::is_lockable_for_v

inlineconstexpr

Initial value:

=
    is_lockable_for<Lock, Duration>::value

Helper variable template for is_lockable_for<Lock, Duration>::value.

is_lockable_until_v

template<typename Lock , typename TimePoint >

constexpr bool pw::sync::is_lockable_until_v

inlineconstexpr

Initial value:

=
    is_lockable_until<Lock, TimePoint>::value

Helper variable template for is_lockable_until<Lock, TimePoint>::value.

is_timed_lockable_v

template<typename Lock , typename Clock >

constexpr bool pw::sync::is_timed_lockable_v

inlineconstexpr

Initial value:

=
    is_timed_lockable<Lock, Clock>::value

Helper variable template for is_timed_lockable<Lock, Clock>::value.