pw_sync: Add ThreadNotification note in docs
Adds blurb for the ThreadNotification to make it more obvious that
unlike some native RTOS APIs such as direct task signaling, multiple
ThreadNotifications may be used by a single thread.
Change-Id: I3e79581a7b40c30660c211c0d5be2a052afb722e
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/58140
Pigweed-Auto-Submit: Ewout van Bekkum <ewout@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Reviewed-by: Keir Mierle <keir@google.com>
diff --git a/pw_sync/docs.rst b/pw_sync/docs.rst
index 5d77eca..8d4372f 100644
--- a/pw_sync/docs.rst
+++ b/pw_sync/docs.rst
@@ -215,7 +215,7 @@
Note that the ``TimedMutex`` is a derived ``Mutex`` class, meaning that
a ``TimedMutex`` can be used by someone who needs the basic ``Mutex``. This is
-in stark contrast to the C++ STL's
+in contrast to the C++ STL's
`std::timed_mutex <https://en.cppreference.com/w/cpp/thread/timed_mutex>`_.
@@ -974,6 +974,12 @@
permit a SINGLE thread to block and consume a latching, saturating
notification from multiple notifiers.
+.. Note::
+ Although only a single thread can block on a ThreadNotification at a time,
+ many instances may be used by a single thread just like binary semaphores.
+ This is in contrast to some native RTOS APIs, such as direct task
+ notifications, which re-use the same state within a thread's context.
+
.. Warning::
This is a single consumer/waiter, multiple producer/notifier API!
The acquire APIs must only be invoked by a single consuming thread. As a