diff options
Diffstat (limited to 'pw_sync/docs.rst')
| -rw-r--r-- | pw_sync/docs.rst | 31 |
1 files changed, 26 insertions, 5 deletions
diff --git a/pw_sync/docs.rst b/pw_sync/docs.rst index e30c01f51..aba3ea4c7 100644 --- a/pw_sync/docs.rst +++ b/pw_sync/docs.rst @@ -731,9 +731,9 @@ internal mutex, however at crash time we may want to switch to a no-op lock. A virtual lock interface could be used here to minimize the code-size cost that would occur otherwise if the flash driver were templated. -VirtualBasicLock ----------------- -The ``VirtualBasicLock`` interface meets the +VirtualBasicLockable +-------------------- +The ``VirtualBasicLockable`` interface meets the `BasicLockable <https://en.cppreference.com/w/cpp/named_req/BasicLockable>`_ C++ named requirement. Our critical section lock primitives offer optional virtual versions, including: @@ -742,9 +742,24 @@ versions, including: * :cpp:func:`pw::sync::VirtualTimedMutex` * :cpp:func:`pw::sync::VirtualInterruptSpinLock` +.. _module-pw_sync-genericbasiclockable: + +GenericBasicLockable +-------------------- +``GenericBasicLockable`` is a helper construct that can be used to declare +virtual versions of a critical section lock primitive that meets the +`BasicLockable <https://en.cppreference.com/w/cpp/named_req/BasicLockable>`_ +C++ named requirement. For example, given a ``Mutex`` type with ``lock()`` and +``unlock()`` methods, a ``VirtualMutex`` type that derives from +``VirtualBasicLockable`` can be declared as follows: + +.. code-block:: cpp + + class VirtualMutex : public GenericBasicLockable<Mutex> {}; + Borrowable ========== -The Borrowable is a helper construct that enables callers to borrow an object +``Borrowable`` is a helper construct that enables callers to borrow an object which is guarded by a lock, enabling a containerized style of external locking. Users who need access to the guarded object can ask to acquire a @@ -871,6 +886,12 @@ into the ACK timeout you'd like to use for the transaction. Borrowable can help you do exactly this if you provide access to the I2c bus through a ``Borrowable``. +.. note:: + + ``Borrowable`` has semantics similar to a pointer and should be passed by + value. Furthermore, a ``Borrowable<U>`` can be assigned to a + ``Borrowable<T>`` if ``U`` is a subclass of ``T``. + C++ --- .. doxygenclass:: pw::sync::BorrowedPointer @@ -1008,7 +1029,7 @@ Example in C++ pw::sync::InlineBorrowable<ExampleI2c> i2c(std::in_place, kBusId, opts); pw::Result<ConstByteSpan> ReadI2cData( - pw::sync::Borrowable<pw::i2c::Initiator>& initiator, + pw::sync::Borrowable<pw::i2c::Initiator> initiator, ByteSpan buffer); pw::Result<ConstByteSpan> ReadData(ByteSpan buffer) { |