64 lines
2.6 KiB
ReStructuredText
64 lines
2.6 KiB
ReStructuredText
.. _module-pw_sync_threadx:
|
|
|
|
===============
|
|
pw_sync_threadx
|
|
===============
|
|
This is a set of backends for pw_sync based on ThreadX.
|
|
|
|
It is possible, if necessary, to use pw_sync_threadx without using the Pigweed
|
|
provided pw_chrono_threadx in case the ThreadX time API (``tx_time_get()``)) is
|
|
not available (i.e. ``TX_NO_TIMER`` is set). You are responsible for ensuring
|
|
that the chrono backend provided has counts which match the ThreadX tick based
|
|
API.
|
|
|
|
--------------------------------
|
|
Critical Section Lock Primitives
|
|
--------------------------------
|
|
|
|
Mutex & TimedMutex
|
|
==================
|
|
The ThreadX backend for the Mutex and TimedMutex use ``TX_MUTEX`` as the
|
|
underlying type. It is created using ``tx_mutex_create`` as part of the
|
|
constructors and cleaned up using ``tx_mutex_delete`` in the destructors.
|
|
|
|
InterruptSpinLock
|
|
=================
|
|
The ThreadX backend for InterruptSpinLock is backed by an ``enum class`` and
|
|
two ``UINT`` which permits these objects to detect accidental recursive locking
|
|
and unlocking contexts.
|
|
|
|
This object uses ``tx_interrupt_control`` to enable critical sections. In
|
|
addition, ``tx_thread_preemption_change`` is used to prevent accidental thread
|
|
context switches while the InterruptSpinLock is held by a thread.
|
|
|
|
.. Warning::
|
|
This backend does not support SMP yet as there's no internal lock to spin on.
|
|
|
|
--------------------
|
|
Signaling Primitives
|
|
--------------------
|
|
|
|
ThreadNotification & TimedThreadNotification
|
|
============================================
|
|
The native ThreadX API does cover direct thread signaling and ergo we recommend
|
|
using the binary semaphore backends for ThreadNotifications:
|
|
- ``pw_sync:binary_semaphore_thread_notification_backend``
|
|
- ``pw_sync:binary_semaphore_timed_thread_notification_backend``
|
|
|
|
Background Information
|
|
----------------------
|
|
Although one may be tempted to use ``tx_thread_sleep`` and
|
|
``tx_thread_wait_abort`` to implement direct thread notifications with ThreadX,
|
|
this unfortunately cannot work. Between the blocking thread setting its
|
|
``TX_THREAD*`` handle and actually executing ``tx_thread_sleep`` there will
|
|
always exist a race condition. Another thread and/or interrupt may attempt
|
|
to invoke ``tx_thread_wait_abort`` before the blocking thread has executed
|
|
``tx_thread_sleep`` meaning the wait abort would fail.
|
|
|
|
BinarySemaphore & CountingSemaphore
|
|
===================================
|
|
The ThreadX backends for the BinarySemaphore and CountingSemaphore use
|
|
``TX_SEMAPHORE`` as the underlying type. It is created using
|
|
``tx_semaphore_create`` as part of the constructor and cleaned up using
|
|
``tx_semaphore_delete`` in the destructor.
|