| .. _module-pw_sync: |
| |
| ======= |
| pw_sync |
| ======= |
| The ``pw_sync`` module contains utilities for synchronizing between threads |
| and/or interrupts through signaling primitives and critical section lock |
| primitives. |
| |
| .. contents:: |
| :local: |
| :depth: 2 |
| |
| .. Warning:: |
| This module is still under construction, the API is not yet stable. |
| |
| .. Note:: |
| The objects in this module do not have an Init() style public API which is |
| common in many RTOS C APIs. Instead, they rely on being able to invoke the |
| native initialization APIs for synchronization primitives during C++ |
| construction. |
| In order to support global statically constructed synchronization without |
| constexpr constructors, the user and/or backend **MUST** ensure that any |
| initialization required in your environment is done prior to the creation |
| and/or initialization of the native synchronization primitives |
| (e.g. kernel initialization). |
| |
| -------------------------------- |
| Critical Section Lock Primitives |
| -------------------------------- |
| The critical section lock primitives provided by this module comply with |
| `BasicLockable <https://en.cppreference.com/w/cpp/named_req/BasicLockable>`_, |
| `Lockable <https://en.cppreference.com/w/cpp/named_req/Lockable>`_, and where |
| relevant |
| `TimedLockable <https://en.cppreference.com/w/cpp/named_req/TimedLockable>`_ C++ |
| named requirements. This means that they are compatible with existing helpers in |
| the STL's ``<mutex>`` thread support library. For example `std::lock_guard <https://en.cppreference.com/w/cpp/thread/lock_guard>`_ |
| and `std::unique_lock <https://en.cppreference.com/w/cpp/thread/unique_lock>`_ can be directly used. |
| |
| Mutex |
| ===== |
| The Mutex is a synchronization primitive that can be used to protect shared data |
| from being simultaneously accessed by multiple threads. It offers exclusive, |
| non-recursive ownership semantics where priority inheritance is used to solve |
| the classic priority-inversion problem. |
| |
| The Mutex's API is C++11 STL |
| `std::timed_mutex <https://en.cppreference.com/w/cpp/thread/timed_mutex>`_ like, |
| meaning it is a |
| `BasicLockable <https://en.cppreference.com/w/cpp/named_req/BasicLockable>`_, |
| `Lockable <https://en.cppreference.com/w/cpp/named_req/Lockable>`_, and |
| `TimedLockable <https://en.cppreference.com/w/cpp/named_req/TimedLockable>`_. |
| |
| .. Warning:: |
| This interface will likely be split between a Mutex and TimedMutex to ease |
| portability for baremetal support. |
| |
| .. list-table:: |
| |
| * - *Supported on* |
| - *Backend module* |
| * - FreeRTOS |
| - :ref:`module-pw_sync_freertos` |
| * - ThreadX |
| - :ref:`module-pw_sync_threadx` |
| * - embOS |
| - :ref:`module-pw_sync_embos` |
| * - STL |
| - :ref:`module-pw_sync_stl` |
| * - Baremetal |
| - Planned |
| * - Zephyr |
| - Planned |
| * - CMSIS-RTOS API v2 & RTX5 |
| - Planned |
| |
| C++ |
| --- |
| .. cpp:class:: pw::sync::Mutex |
| |
| .. cpp:function:: void lock() |
| |
| Locks the mutex, blocking indefinitely. Failures are fatal. |
| |
| **Precondition:** The lock isn't already held by this thread. Recursive |
| locking is undefined behavior. |
| |
| .. cpp:function:: bool try_lock() |
| |
| Attempts to lock the mutex in a non-blocking manner. |
| Returns true if the mutex was successfully acquired. |
| |
| **Precondition:** The lock isn't already held by this thread. Recursive |
| locking is undefined behavior. |
| |
| .. cpp:function:: bool try_lock_for(chrono::SystemClock::duration for_at_least) |
| |
| Attempts to lock the mutex where, if needed, blocking for at least the |
| specified duration. |
| Returns true if the mutex was successfully acquired. |
| |
| **Precondition:** The lock isn't already held by this thread. Recursive |
| locking is undefined behavior. |
| |
| .. cpp:function:: bool try_lock_until(chrono::SystemClock::time_point until_at_least) |
| |
| Attempts to lock the mutex where, if needed, blocking until at least the |
| specified time_point. |
| Returns true if the mutex was successfully acquired. |
| |
| **Precondition:** The lock isn't already held by this thread. Recursive |
| locking is undefined behavior. |
| |
| .. cpp:function:: void unlock() |
| |
| Unlocks the mutex. Failures are fatal. |
| |
| **Precondition:** The mutex is held by this thread. |
| |
| |
| .. list-table:: |
| |
| * - *Safe to use in context* |
| - *Thread* |
| - *Interrupt* |
| - *NMI* |
| * - ``Mutex::Mutex`` |
| - ✔ |
| - |
| - |
| * - ``Mutex::~Mutex`` |
| - ✔ |
| - |
| - |
| * - ``void Mutex::lock`` |
| - ✔ |
| - |
| - |
| * - ``bool Mutex::try_lock`` |
| - ✔ |
| - |
| - |
| * - ``bool Mutex::try_lock_for`` |
| - ✔ |
| - |
| - |
| * - ``bool Mutex::try_lock_until`` |
| - ✔ |
| - |
| - |
| * - ``void Mutex::unlock`` |
| - ✔ |
| - |
| - |
| |
| Examples in C++ |
| ^^^^^^^^^^^^^^^ |
| .. code-block:: cpp |
| |
| #include "pw_chrono/system_clock.h" |
| #include "pw_sync/mutex.h" |
| |
| pw::sync::Mutex mutex; |
| |
| void ThreadSafeCriticalSection() { |
| mutex.lock(); |
| NotThreadSafeCriticalSection(); |
| mutex.unlock(); |
| } |
| |
| bool ThreadSafeCriticalSectionWithTimeout( |
| const SystemClock::duration timeout) { |
| if (!mutex.try_lock_for(timeout)) { |
| return false; |
| } |
| NotThreadSafeCriticalSection(); |
| mutex.unlock(); |
| return true; |
| } |
| |
| |
| Alternatively you can use C++'s RAII helpers to ensure you always unlock. |
| |
| .. code-block:: cpp |
| |
| #include <mutex> |
| |
| #include "pw_chrono/system_clock.h" |
| #include "pw_sync/mutex.h" |
| |
| pw::sync::Mutex mutex; |
| |
| void ThreadSafeCriticalSection() { |
| std::lock_guard lock(mutex); |
| NotThreadSafeCriticalSection(); |
| } |
| |
| bool ThreadSafeCriticalSectionWithTimeout( |
| const SystemClock::duration timeout) { |
| std::unique_lock lock(mutex, std::defer_lock); |
| if (!lock.try_lock_for(timeout)) { |
| return false; |
| } |
| NotThreadSafeCriticalSection(); |
| return true; |
| } |
| |
| |
| |
| C |
| - |
| The Mutex must be created in C++, however it can be passed into C using the |
| ``pw_sync_Mutex`` opaque struct alias. |
| |
| .. cpp:function:: void pw_sync_Mutex_Lock(pw_sync_Mutex* mutex) |
| |
| Invokes the ``Mutex::lock`` member function on the given ``mutex``. |
| |
| .. cpp:function:: bool pw_sync_Mutex_TryLock(pw_sync_Mutex* mutex) |
| |
| Invokes the ``Mutex::try_lock`` member function on the given ``mutex``. |
| |
| .. cpp:function:: bool pw_sync_Mutex_TryLockFor(pw_sync_Mutex* mutex, pw_chrono_SystemClock_Duration for_at_least) |
| |
| Invokes the ``Mutex::try_lock_for`` member function on the given ``mutex``. |
| |
| .. cpp:function:: bool pw_sync_Mutex_TryLockUntil(pw_sync_Mutex* mutex, pw_chrono_SystemClock_TimePoint until_at_least) |
| |
| Invokes the ``Mutex::try_lock_until`` member function on the given ``mutex``. |
| |
| .. cpp:function:: void pw_sync_Mutex_Unlock(pw_sync_Mutex* mutex) |
| |
| Invokes the ``Mutex::unlock`` member function on the given ``mutex``. |
| |
| .. list-table:: |
| |
| * - *Safe to use in context* |
| - *Thread* |
| - *Interrupt* |
| - *NMI* |
| * - ``void pw_sync_Mutex_Lock`` |
| - ✔ |
| - |
| - |
| * - ``bool pw_sync_Mutex_TryLock`` |
| - ✔ |
| - |
| - |
| * - ``bool pw_sync_Mutex_TryLockFor`` |
| - ✔ |
| - |
| - |
| * - ``bool pw_sync_Mutex_TryLockUntil`` |
| - ✔ |
| - |
| - |
| * - ``void pw_sync_Mutex_Unlock`` |
| - ✔ |
| - |
| - |
| |
| Example in C |
| ^^^^^^^^^^^^ |
| .. code-block:: cpp |
| |
| #include "pw_chrono/system_clock.h" |
| #include "pw_sync/mutex.h" |
| |
| pw::sync::Mutex mutex; |
| |
| extern pw_sync_Mutex mutex; // This can only be created in C++. |
| |
| void ThreadSafeCriticalSection(void) { |
| pw_sync_Mutex_Lock(&mutex); |
| NotThreadSafeCriticalSection(); |
| pw_sync_Mutex_Unlock(&mutex); |
| } |
| |
| bool ThreadSafeCriticalSectionWithTimeout( |
| const pw_chrono_SystemClock_Duration timeout) { |
| if (!pw_sync_Mutex_TryLockFor(&mutex, timeout)) { |
| return false; |
| } |
| NotThreadSafeCriticalSection(); |
| pw_sync_Mutex_Unlock(&mutex); |
| return true; |
| } |
| |
| |
| InterruptSpinLock |
| ================= |
| The InterruptSpinLock is a synchronization primitive that can be used to protect |
| shared data from being simultaneously accessed by multiple threads and/or |
| interrupts as a targeted global lock, with the exception of Non-Maskable |
| Interrupts (NMIs). It offers exclusive, non-recursive ownership semantics where |
| IRQs up to a backend defined level of "NMIs" will be masked to solve |
| priority-inversion. |
| |
| This InterruptSpinLock relies on built-in local interrupt masking to make it |
| interrupt safe without requiring the caller to separately mask and unmask |
| interrupts when using this primitive. |
| |
| Unlike global interrupt locks, this also works safely and efficiently on SMP |
| systems. On systems which are not SMP, spinning is not required but some state |
| may still be used to detect recursion. |
| |
| The InterruptSpinLock is a |
| `BasicLockable <https://en.cppreference.com/w/cpp/named_req/BasicLockable>`_ |
| and |
| `Lockable <https://en.cppreference.com/w/cpp/named_req/Lockable>`_. |
| |
| .. list-table:: |
| |
| * - *Supported on* |
| - *Backend module* |
| * - FreeRTOS |
| - :ref:`module-pw_sync_freertos` |
| * - ThreadX |
| - :ref:`module-pw_sync_threadx` |
| * - embOS |
| - :ref:`module-pw_sync_embos` |
| * - STL |
| - :ref:`module-pw_sync_stl` |
| * - Baremetal |
| - Planned, not ready for use |
| * - Zephyr |
| - Planned |
| * - CMSIS-RTOS API v2 & RTX5 |
| - Planned |
| |
| C++ |
| --- |
| .. cpp:class:: pw::sync::InterruptSpinLock |
| |
| .. cpp:function:: void lock() |
| |
| Locks the spinlock, blocking indefinitely. Failures are fatal. |
| |
| **Precondition:** Recursive locking is undefined behavior. |
| |
| .. cpp:function:: bool try_lock() |
| |
| Attempts to lock the spinlock in a non-blocking manner. |
| Returns true if the spinlock was successfully acquired. |
| |
| **Precondition:** Recursive locking is undefined behavior. |
| |
| .. cpp:function:: void unlock() |
| |
| Unlocks the mutex. Failures are fatal. |
| |
| **Precondition:** The spinlock is held by the caller. |
| |
| .. list-table:: |
| |
| * - *Safe to use in context* |
| - *Thread* |
| - *Interrupt* |
| - *NMI* |
| * - ``InterruptSpinLock::InterruptSpinLock`` |
| - ✔ |
| - ✔ |
| - |
| * - ``InterruptSpinLock::~InterruptSpinLock`` |
| - ✔ |
| - ✔ |
| - |
| * - ``void InterruptSpinLock::lock`` |
| - ✔ |
| - ✔ |
| - |
| * - ``bool InterruptSpinLock::try_lock`` |
| - ✔ |
| - ✔ |
| - |
| * - ``void InterruptSpinLock::unlock`` |
| - ✔ |
| - ✔ |
| - |
| |
| Examples in C++ |
| ^^^^^^^^^^^^^^^ |
| .. code-block:: cpp |
| |
| #include "pw_sync/interrupt_spin_lock.h" |
| |
| pw::sync::InterruptSpinLock interrupt_spin_lock; |
| |
| void InterruptSafeCriticalSection() { |
| interrupt_spin_lock.lock(); |
| NotThreadSafeCriticalSection(); |
| interrupt_spin_lock.unlock(); |
| } |
| |
| |
| Alternatively you can use C++'s RAII helpers to ensure you always unlock. |
| |
| .. code-block:: cpp |
| |
| #include <mutex> |
| |
| #include "pw_sync/interrupt_spin_lock.h" |
| |
| pw::sync::InterruptSpinLock interrupt_spin_lock; |
| |
| void InterruptSafeCriticalSection() { |
| std::lock_guard lock(interrupt_spin_lock); |
| NotThreadSafeCriticalSection(); |
| } |
| |
| |
| C |
| - |
| The InterruptSpinLock must be created in C++, however it can be passed into C using the |
| ``pw_sync_InterruptSpinLock`` opaque struct alias. |
| |
| .. cpp:function:: void pw_sync_InterruptSpinLock_Lock(pw_sync_InterruptSpinLock* interrupt_spin_lock) |
| |
| Invokes the ``InterruptSpinLock::lock`` member function on the given ``interrupt_spin_lock``. |
| |
| .. cpp:function:: bool pw_sync_InterruptSpinLock_TryLock(pw_sync_InterruptSpinLock* interrupt_spin_lock) |
| |
| Invokes the ``InterruptSpinLock::try_lock`` member function on the given ``interrupt_spin_lock``. |
| |
| .. cpp:function:: void pw_sync_InterruptSpinLock_Unlock(pw_sync_InterruptSpinLock* interrupt_spin_lock) |
| |
| Invokes the ``InterruptSpinLock::unlock`` member function on the given ``interrupt_spin_lock``. |
| |
| .. list-table:: |
| |
| * - *Safe to use in context* |
| - *Thread* |
| - *Interrupt* |
| - *NMI* |
| * - ``void pw_sync_InterruptSpinLock_Lock`` |
| - ✔ |
| - ✔ |
| - |
| * - ``bool pw_sync_InterruptSpinLock_TryLock`` |
| - ✔ |
| - ✔ |
| - |
| * - ``void pw_sync_InterruptSpinLock_Unlock`` |
| - ✔ |
| - ✔ |
| - |
| |
| Example in C |
| ^^^^^^^^^^^^ |
| .. code-block:: cpp |
| |
| #include "pw_chrono/system_clock.h" |
| #include "pw_sync/interrupt_spin_lock.h" |
| |
| pw::sync::InterruptSpinLock interrupt_spin_lock; |
| |
| extern pw_sync_InterruptSpinLock interrupt_spin_lock; // This can only be created in C++. |
| |
| void InterruptSafeCriticalSection(void) { |
| pw_sync_InterruptSpinLock_Lock(&interrupt_spin_lock); |
| NotThreadSafeCriticalSection(); |
| pw_sync_InterruptSpinLock_Unlock(&interrupt_spin_lock); |
| } |
| |
| |
| -------------------- |
| Signaling Primitives |
| -------------------- |
| |
| Native signaling primitives tend to vary more compared to critial section locks |
| across different platforms. For example, although common signaling primtives |
| like semaphores are in most if not all RTOSes and even POSIX, it was not in the |
| STL before C++20. Likewise many C++ developers are surprised that conditional |
| variables tend to not be natively supported on RTOSes. Although you can usually |
| build any signaling primitive based on other native signaling primitives, this |
| may come with non-trivial added overhead in ROM, RAM, and execution efficiency. |
| |
| For this reason, Pigweed intends to provide some "simpler" signaling primitives |
| which exist to solve a narrow programming need but can be implemented as |
| efficiently as possible for the platform that it is used on. |
| |
| This simpler but highly portable class of signaling primitives is intended to |
| ensure that a portability efficiency tradeoff does not have to be made up front. |
| For example we intend to provide a ``pw::sync::Notification`` facade which |
| permits a singler consumer to block until an event occurs. This should be |
| backed by the most efficient native primitive for a target, regardless of |
| whether that is a semaphore, event flag group, condition variable, or something |
| else. |
| |
| CountingSemaphore |
| ================= |
| The CountingSemaphore is a synchronization primitive that can be used for |
| counting events and/or resource management where receiver(s) can block on |
| acquire until notifier(s) signal by invoking release. |
| |
| Note that unlike Mutexes, priority inheritance is not used by semaphores meaning |
| semaphores are subject to unbounded priority inversions. Due to this, Pigweed |
| does not recommend semaphores for mutual exclusion. |
| |
| The CountingSemaphore is initialized to being empty or having no tokens. |
| |
| The entire API is thread safe, but only a subset is interrupt safe. None of it |
| is NMI safe. |
| |
| .. Warning:: |
| Releasing multiple tokens is often not natively supported, meaning you may |
| end up invoking the native kernel API many times, i.e. once per token you |
| are releasing! |
| |
| .. list-table:: |
| |
| * - *Supported on* |
| - *Backend module* |
| * - FreeRTOS |
| - :ref:`module-pw_sync_freertos` |
| * - ThreadX |
| - :ref:`module-pw_sync_threadx` |
| * - embOS |
| - :ref:`module-pw_sync_embos` |
| * - STL |
| - :ref:`module-pw_sync_stl` |
| * - Zephyr |
| - Planned |
| * - CMSIS-RTOS API v2 & RTX5 |
| - Planned |
| |
| BinarySemaphore |
| =============== |
| BinarySemaphore is a specialization of CountingSemaphore with an arbitrary token |
| limit of 1. Note that that ``max()`` is >= 1, meaning it may be released up to |
| ``max()`` times but only acquired once for those N releases. |
| |
| Implementations of BinarySemaphore are typically more efficient than the |
| default implementation of CountingSemaphore. |
| |
| The BinarySemaphore is initialized to being empty or having no tokens. |
| |
| The entire API is thread safe, but only a subset is interrupt safe. None of it |
| is NMI safe. |
| |
| .. list-table:: |
| |
| * - *Supported on* |
| - *Backend module* |
| * - FreeRTOS |
| - :ref:`module-pw_sync_freertos` |
| * - ThreadX |
| - :ref:`module-pw_sync_threadx` |
| * - embOS |
| - :ref:`module-pw_sync_embos` |
| * - STL |
| - :ref:`module-pw_sync_stl` |
| * - Zephyr |
| - Planned |
| * - CMSIS-RTOS API v2 & RTX5 |
| - Planned |
| |
| Coming Soon |
| =========== |
| We are intending to provide facades for: |
| |
| * ``pw::sync::Notification``: A portable abstraction to allow threads to receive |
| notification of a single occurrence of a single event. |
| |
| * ``pw::sync::EventGroup`` A facade for a common primitive on RTOSes like |
| FreeRTOS, RTX5, ThreadX, and embOS which permit threads and interrupts to |
| signal up to 32 events. This permits others threads to be notified when either |
| any or some combination of these events have been signaled. This is frequently |
| used as an alternative to a set of binary semaphore(s). This is not supported |
| natively on Zephyr. |