1.. _module-pw_sync_threadx: 2 3=============== 4pw_sync_threadx 5=============== 6This is a set of backends for pw_sync based on ThreadX. 7 8It is possible, if necessary, to use pw_sync_threadx without using the Pigweed 9provided pw_chrono_threadx in case the ThreadX time API (``tx_time_get()``)) is 10not available (i.e. ``TX_NO_TIMER`` is set). You are responsible for ensuring 11that the chrono backend provided has counts which match the ThreadX tick based 12API. 13 14-------------------------------- 15Critical Section Lock Primitives 16-------------------------------- 17 18Mutex & TimedMutex 19================== 20The ThreadX backend for the Mutex and TimedMutex use ``TX_MUTEX`` as the 21underlying type. It is created using ``tx_mutex_create`` as part of the 22constructors and cleaned up using ``tx_mutex_delete`` in the destructors. 23 24InterruptSpinLock 25================= 26The ThreadX backend for InterruptSpinLock is backed by an ``enum class`` and 27two ``UINT`` which permits these objects to detect accidental recursive locking 28and unlocking contexts. 29 30This object uses ``tx_interrupt_control`` to enable critical sections. In 31addition, ``tx_thread_preemption_change`` is used to prevent accidental thread 32context switches while the InterruptSpinLock is held by a thread. 33 34.. Warning:: 35 This backend does not support SMP yet as there's no internal lock to spin on. 36 37-------------------- 38Signaling Primitives 39-------------------- 40 41ThreadNotification & TimedThreadNotification 42============================================ 43Prefer using the binary semaphore backends for ThreadNotifications as 44the native ThreadX API covers direct thread signaling: 45 46- ``pw_sync:binary_semaphore_thread_notification_backend`` 47- ``pw_sync:binary_semaphore_timed_thread_notification_backend`` 48 49Background Information 50---------------------- 51Although one may be tempted to use ``tx_thread_sleep`` and 52``tx_thread_wait_abort`` to implement direct thread notifications with ThreadX, 53this unfortunately cannot work. Between the blocking thread setting its 54``TX_THREAD*`` handle and actually executing ``tx_thread_sleep`` there will 55always exist a race condition. Another thread and/or interrupt may attempt 56to invoke ``tx_thread_wait_abort`` before the blocking thread has executed 57``tx_thread_sleep`` meaning the wait abort would fail. 58 59BinarySemaphore & CountingSemaphore 60=================================== 61The ThreadX backends for the BinarySemaphore and CountingSemaphore use 62``TX_SEMAPHORE`` as the underlying type. It is created using 63``tx_semaphore_create`` as part of the constructor and cleaned up using 64``tx_semaphore_delete`` in the destructor. 65