|
SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
|
Counting semaphore primitive for resource management and signaling, with a selectable counter type. More...
#include <stk_sync_semaphore.h>
Classes | |
| struct | ReadTag |
| Selects how the counter is read: WIDE is true if T is wider than a pointer. More... | |
Public Types | |
| typedef T | CounterValueType |
| Counter value type. | |
| typedef DLHeadType | ListHeadType |
| List head type for ISyncObject elements. | |
| typedef DLEntryType | ListEntryType |
| List entry type of ISyncObject elements. | |
| enum | |
| A tag for type-safe casts done by CastListEntryToParent. More... | |
| typedef DListEntry< ISyncObject, TClosedLoop > | DLEntryType |
| Convenience alias for this entry type. Used to avoid repeating the full template spelling. | |
| typedef DListHead< ISyncObject, TClosedLoop > | DLHeadType |
| Convenience alias for the corresponding list head type. | |
Public Member Functions | |
| SemaphoreT (T initial_count=0U, T max_count=COUNT_MAX) | |
| Constructor. | |
| ~SemaphoreT () | |
| Destructor. | |
| EWaitResult | WaitEx (Timeout timeout_ticks=WAIT_INFINITE) |
| Wait for a signal (decrement counter), preserving the full wait outcome. | |
| bool | Wait (Timeout timeout_ticks=WAIT_INFINITE) |
| Wait for a signal (decrement counter). | |
| bool | TryWait () |
| Poll the semaphore without blocking (decrement counter if available). | |
| void | Signal () |
| Post a signal (increment counter). | |
| bool | TrySignal () |
| Try to post a signal without exceeding max_count. | |
| bool | TrySignal (const T ceiling) |
| Try to post a signal without exceeding a caller-supplied ceiling. | |
| T | GetCount () const |
| Get current counter value. | |
| void | AddWaitObject (IWaitObject *wobj) override |
| Called by kernel when a new task starts waiting on this event. | |
| void | RemoveWaitObject (IWaitObject *wobj) override |
| Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.). | |
| const IWaitObject::ListHeadType & | GetWaitList () const override |
| Get list of tasks blocked on this object. | |
| virtual bool | Tick (Timeout elapsed_ticks) |
| Called by kernel on every system tick to handle timeout logic of waiting tasks. | |
| Weight | FindWeightHigherThan (Weight comp) const |
| Find higher weight within linked wait objects. | |
| TId | GetFirstWaiterTid () const |
| Get id of the task which is first in the wait list (FIFO order), i.e. the one that WakeOne() would wake next. | |
| DLHeadType * | GetHead () |
| Get the list head this entry currently belongs to. | |
| DLEntryType * | GetNext () |
| Get the next entry in the list. | |
| DLEntryType * | GetPrev () |
| Get the previous entry in the list. | |
| bool | IsLinked () const |
| Check whether this entry is currently a member of any list. | |
| operator ISyncObject * () | |
| Implicit conversion to a mutable pointer to the host object (T). | |
| operator const ISyncObject * () const | |
| Implicit conversion to a const pointer to the host object (T). | |
| void | SetTraceName (const char *name) |
| Set name. | |
| const char * | GetTraceName () const |
| Get name. | |
Static Public Member Functions | |
| static void | AddWaitObject (IWaitObject::ListHeadType &wlist, IWaitObject *wobj) |
| Called by kernel when a new task starts waiting on this event. | |
| static void | RemoveWaitObject (IWaitObject::ListHeadType &wlist, IWaitObject *wobj) |
| Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.). | |
| static void | WakeOne (IWaitObject::ListHeadType &wlist) |
| Wake the first task in the wait list (FIFO order). | |
| static void | WakeAll (IWaitObject::ListHeadType &wlist) |
| Wake all tasks currently in the wait list. | |
Static Public Attributes | |
| static constexpr T | COUNT_MAX = static_cast<T>(~static_cast<T>(0U)) |
| Max count value supported (maximum value of T). | |
Protected Member Functions | |
| void | WakeOne () override |
| Wake the first task in the wait list (FIFO order). | |
| void | WakeAll () override |
| Wake all tasks currently in the wait list. | |
| IWaitObject::ListHeadType & | GetMutableWaitList () override |
| Get list of tasks blocked on this object. | |
Protected Attributes | |
| IWaitObject::ListHeadType | m_wait_list |
| Tasks blocked on this object. | |
Private Member Functions | |
| SemaphoreT (const SemaphoreT &)=delete | |
| SemaphoreT & | operator= (const SemaphoreT &)=delete |
| T | ReadCount (ReadTag< false >) const |
| Counter fits the native word: a single load is atomic. | |
| T | ReadCount (ReadTag< true >) const |
| Counter is wider than the native word: a plain load may be split into several, guard it. | |
| bool | TrySignalLimited (const T limit) |
| Common signal path: hand off to a waiter or increment up to limit. | |
| void | Link (DLHeadType *head, DLEntryType *next, DLEntryType *prev) |
| Wire this entry into a list between prev and next. | |
| void | Unlink () |
| Remove this entry from its current list. | |
Private Attributes | |
| T | m_count |
| Internal resource counter. | |
| T | m_count_max |
| Counter max limit. | |
| DLHeadType * | m_head |
Owning list head, or NULL when the entry is not linked. | |
| DLEntryType * | m_next |
Next entry in the list, or NULL (open list boundary) / first entry (closed loop). | |
| DLEntryType * | m_prev |
Previous entry in the list, or NULL (open list boundary) / last entry (closed loop). | |
Counting semaphore primitive for resource management and signaling, with a selectable counter type.
Counting semaphore maintains an internal counter to manage access to a limited number of resources. Unlike a Condition Variable, a Semaphore is stateful: if Signal() is called when no tasks are waiting, the signal is "remembered" by incrementing the internal counter.
| T | Unsigned integer type used for the counter and its limit (e.g. uint8_t, uint16_t, uint32_t, uint64_t). Signed types are rejected at compile time. Note that uint8_t does not necessarily reduce the object size because of alignment padding, verify with sizeof() on your target before relying on it. A type wider than a pointer (e.g. uint64_t on a 32-bit MCU) is supported: all counter updates are done under the critical section, and GetCount() takes it as well so that the value can not be read torn. |
Signal() gives the resource "token" directly to the first task in the wait list without incrementing the counter. The waking task is then guaranteed ownership of that token upon returning from Wait().Definition at line 71 of file stk_sync_semaphore.h.
| typedef T stk::sync::SemaphoreT< T >::CounterValueType |
Counter value type.
Definition at line 78 of file stk_sync_semaphore.h.
|
inherited |
Convenience alias for this entry type. Used to avoid repeating the full template spelling.
Definition at line 75 of file stk_linked_list.h.
|
inherited |
Convenience alias for the corresponding list head type.
Definition at line 80 of file stk_linked_list.h.
|
inherited |
List entry type of ISyncObject elements.
Definition at line 672 of file stk_common.h.
|
inherited |
List head type for ISyncObject elements.
Definition at line 667 of file stk_common.h.
|
inherited |
A tag for type-safe casts done by CastListEntryToParent.
Definition at line 70 of file stk_linked_list.h.
|
inlineexplicit |
Constructor.
Initializes the semaphore with a specific count and maximum limit. Setting initial_count to a non-zero value allows for immediate resource acquisition.
| [in] | initial_count | Starting value of the internal counter (available permits). |
| [in] | max_count | Maximum value the counter is allowed to reach. |
Definition at line 93 of file stk_sync_semaphore.h.
|
inline |
Destructor.
Definition at line 105 of file stk_sync_semaphore.h.
|
privatedelete |
|
inlinestaticinherited |
Called by kernel when a new task starts waiting on this event.
| [in] | wlist | Wait list. |
| [in] | wobj | Wait object representing blocked task. |
Definition at line 679 of file stk_common.h.
References stk::detail::DListEntry< T, TClosedLoop >::GetHead(), stk::detail::DListHead< T, TClosedLoop >::LinkBack(), and STK_ASSERT.
Referenced by stk::SyncObjectBase::AddWaitObject(), and stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::SetupWait().
|
inlineoverridevirtualinherited |
Called by kernel when a new task starts waiting on this event.
| [in] | wobj | Wait object representing blocked task. |
Implements stk::ISyncObject.
Definition at line 255 of file stk_helper.h.
References stk::ISyncObject::AddWaitObject(), and m_wait_list.
Find higher weight within linked wait objects.
Implementation of ISyncObject::FindWeightHigherThan, see ISyncObject. Placed here as it depends on GetUserTaskFromTid.
| [in] | comp | Weight to compare with. |
Definition at line 349 of file stk_helper.h.
References stk::detail::DListEntry< T, TClosedLoop >::GetNext(), stk::IWaitObject::GetTid(), stk::GetUserTaskFromTid(), GetWaitList(), stk::ITask::GetWeight(), stk::detail::DListCast::ListEntryToParent(), and stk::NO_WEIGHT.
Referenced by stk::Kernel< TMode, TSize, TStrategy, TPlatform >::OnRestoreWeight(), stk::sync::FastMutex::Unlock(), and stk::sync::Mutex::Unlock().
|
inline |
Get current counter value.
Definition at line 184 of file stk_sync_semaphore.h.
Referenced by sem_getvalue(), stk_sem_get_count(), and xTaskNotifyStateClearIndexed().
|
inlineinherited |
Get id of the task which is first in the wait list (FIFO order), i.e. the one that WakeOne() would wake next.
Definition at line 777 of file stk_common.h.
References stk::IWaitObject::GetTid(), GetWaitList(), stk::detail::DListCast::ListEntryToParent(), and stk::TID_NONE.
|
inlineinherited |
Get the list head this entry currently belongs to.
NULL if the entry is not linked. Definition at line 85 of file stk_linked_list.h.
Referenced by stk::SyncObjectBase::~SyncObjectBase().
|
inlineoverrideprotectedvirtualinherited |
Get list of tasks blocked on this object.
Implements stk::ISyncObject.
Definition at line 306 of file stk_helper.h.
References m_wait_list.
|
inlineinherited |
Get the next entry in the list.
NULL for the last entry; in a closed loop the last entry wraps to the first one, so the result is never NULL for a linked entry. Definition at line 96 of file stk_linked_list.h.
|
inlineinherited |
Get the previous entry in the list.
NULL for the first entry; in a closed loop the first entry wraps to the last one, so the result is never NULL for a linked entry. Definition at line 106 of file stk_linked_list.h.
|
inlineinherited |
Get name.
NULL if not set or if STK_SYNC_DEBUG_NAMES is 0. Definition at line 629 of file stk_common.h.
|
inlineoverridevirtualinherited |
Get list of tasks blocked on this object.
Implements stk::ISyncObject.
Definition at line 265 of file stk_helper.h.
References m_wait_list.
|
inlineinherited |
Check whether this entry is currently a member of any list.
true if linked (m_head != NULL); false otherwise. Definition at line 115 of file stk_linked_list.h.
|
inlineprivateinherited |
Wire this entry into a list between prev and next.
| [in] | head | The owning DListHead. Stored as a back-pointer for IsLinked() and ownership checks. |
| [in] | next | The entry that will follow this one, or NULL if this becomes the last entry. |
| [in] | prev | The entry that will precede this one, or NULL if this becomes the first entry. |
Definition at line 150 of file stk_linked_list.h.
|
inlineinherited |
Implicit conversion to a const pointer to the host object (T).
Definition at line 129 of file stk_linked_list.h.
|
inlineinherited |
Implicit conversion to a mutable pointer to the host object (T).
Definition at line 122 of file stk_linked_list.h.
|
privatedelete |
|
inlineprivate |
Counter fits the native word: a single load is atomic.
Definition at line 193 of file stk_sync_semaphore.h.
Referenced by stk::sync::SemaphoreT< uint16_t >::GetCount().
|
inlineprivate |
Counter is wider than the native word: a plain load may be split into several, guard it.
Definition at line 196 of file stk_sync_semaphore.h.
|
inlinestaticinherited |
Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.).
| [in] | wlist | Wait list. |
| [in] | wobj | Wait object to remove from the wait list. |
Definition at line 696 of file stk_common.h.
References stk::detail::DListEntry< T, TClosedLoop >::GetHead(), STK_ASSERT, and stk::detail::DListHead< T, TClosedLoop >::Unlink().
Referenced by stk::SyncObjectBase::RemoveWaitObject().
|
inlineoverridevirtualinherited |
Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.).
| [in] | wobj | Wait object to remove from the wait list. |
Implements stk::ISyncObject.
Definition at line 260 of file stk_helper.h.
References m_wait_list, and stk::ISyncObject::RemoveWaitObject().
Referenced by stk::sync::Event::RemoveWaitObject().
|
inlineinherited |
Set name.
| [in] | name | Null-terminated string or NULL. |
Definition at line 617 of file stk_common.h.
References STK_UNUSED.
Referenced by stk::memory::BlockMemoryPool::BlockMemoryPool(), stk::memory::BlockMemoryPool::BlockMemoryPool(), stk::memory::BytePool::BytePool(), stk::memory::BytePool::BytePool(), RunExample(), tx_block_pool_create(), tx_mutex_create(), and tx_queue_create().
|
inline |
Post a signal (increment counter).
TrySignal() instead if a signal that would exceed max_count should be tolerated (e.g. a redundant post) rather than treated as a caller error. Definition at line 267 of file stk_sync_semaphore.h.
References STK_ASSERT, STK_UNUSED, and TrySignal().
Referenced by stk_sem_signal().
|
inlinevirtualinherited |
Called by kernel on every system tick to handle timeout logic of waiting tasks.
Implementation of ISyncObject::Tick, see ISyncObject. Placed here as it depends on hw namespace.
| [in] | elapsed_ticks | Number of ticks elapsed between this and previous calls, in case of KERNEL_TICKLESS mode this value can be >1, for non-tickless mode it is always 1. |
true if this synchronization object still has waiters with a finite timeout and requires further tick calls. false if the wait list is empty or all remaining waiters have infinite timeouts, signaling to the kernel that it may stop calling Tick() for this object until a new waiter is added. false, the kernel unlinks this object from its active sync list. It will be re-linked automatically when the next waiter is added via AddWaitObject(). Definition at line 315 of file stk_helper.h.
References stk::detail::DListHead< T, TClosedLoop >::GetFirst(), GetMutableWaitList(), stk::detail::DListEntry< T, TClosedLoop >::GetNext(), stk::detail::DListHead< T, TClosedLoop >::IsEmpty(), stk::detail::DListCast::ListEntryToParent(), stk::IWaitObject::Tick(), and stk::IWaitObject::Wake().
|
inline |
Try to post a signal without exceeding max_count.
Identical to Signal(), except that if the counter is already at max_count and no task is waiting, this returns false instead of asserting. The check and the increment (or hand-off to a waiter) happen atomically under the same critical section, so this is safe to call from multiple concurrent signalers without racing each other the way a separate GetCount() check followed by Signal() would.
true if signaled (incremented, or handed directly to a waiter), false if the counter was already at max_count and nobody was waiting. Definition at line 279 of file stk_sync_semaphore.h.
References m_count_max, and TrySignalLimited().
Referenced by cy_rtos_thread_set_notification(), cy_rtos_thread_terminate(), sem_post(), Signal(), stk_sem_trysignal(), stk_sem_trysignal_ceiling(), ulTaskNotifyTakeIndexed(), xTaskNotifyAndQueryIndexed(), xTaskNotifyGiveIndexed(), and xTaskNotifyIndexed().
|
inline |
Try to post a signal without exceeding a caller-supplied ceiling.
Same as TrySignal(), but the counter is additionally limited by ceiling (the effective limit is the smaller of ceiling and the max_count given at construction). Intended for APIs where the ceiling is a per-call argument (e.g. ThreadX tx_semaphore_ceiling_put). The check and the increment (or hand-off to a waiter) are atomic.
| [in] | ceiling | Maximum counter value allowed for this call. |
true if signaled (incremented, or handed directly to a waiter), false if the counter was already at or above the effective limit and nobody was waiting. Definition at line 285 of file stk_sync_semaphore.h.
References m_count_max, and TrySignalLimited().
|
inlineprivate |
Common signal path: hand off to a waiter or increment up to limit.
| [in] | limit | Effective counter limit for this call. |
true if signaled, false if saturated with no waiter. Definition at line 292 of file stk_sync_semaphore.h.
References m_count, stk::SyncObjectBase::m_wait_list, and stk::SyncObjectBase::WakeOne().
Referenced by TrySignal(), and TrySignal().
|
inline |
Poll the semaphore without blocking (decrement counter if available).
Checks if a resource token is available. If so, decrements the counter and returns immediately without yielding the CPU or touching the kernel wait list. If the counter is zero, returns immediately with false.
true if a resource token was acquired, false if count was zero. Definition at line 136 of file stk_sync_semaphore.h.
Referenced by stk_sem_trywait(), and xTaskNotifyStateClearIndexed().
|
inlineprivateinherited |
Remove this entry from its current list.
Definition at line 174 of file stk_linked_list.h.
|
inline |
Wait for a signal (decrement counter).
| [in] | timeout_ticks | Maximum time to wait (ticks). |
NO_WAIT, ISR-unsafe otherwise. WaitEx() to tell these apart. Definition at line 127 of file stk_sync_semaphore.h.
Referenced by stk_sem_wait(), stk::sync::SemaphoreT< uint16_t >::TryWait(), ulTaskNotifyTakeIndexed(), and xTaskNotifyWaitIndexed().
|
inline |
Wait for a signal (decrement counter), preserving the full wait outcome.
| [in] | timeout_ticks | Maximum time to wait (ticks). |
NO_WAIT, ISR-unsafe otherwise. WAIT_RESULT_SIGNAL if a token was acquired, WAIT_RESULT_TIMEOUT if no token was available and the timeout expired (or NO_WAIT was passed), WAIT_RESULT_CANCELED if the wait was cancelled via IKernel::CancelTaskWait(), WAIT_RESULT_FAIL if the kernel rejected the wait. A non-signal result never consumes a token. Definition at line 230 of file stk_sync_semaphore.h.
References stk::IKernelService::GetInstance(), stk::hw::IsInsideISR(), m_count, stk::NO_WAIT, STK_ASSERT, stk::IKernelService::Wait(), stk::WAIT_RESULT_SIGNAL, and stk::WAIT_RESULT_TIMEOUT.
Referenced by cy_rtos_thread_join(), cy_rtos_thread_wait_notification(), osSemaphoreAcquire(), stk_sem_wait_ex(), and stk::sync::SemaphoreT< uint16_t >::Wait().
|
inlinestaticinherited |
Wake all tasks currently in the wait list.
| [in] | wlist | Wait list. |
Definition at line 752 of file stk_common.h.
References stk::detail::DListHead< T, TClosedLoop >::GetFirst(), and stk::detail::DListCast::ListEntryToParent().
|
inlineoverrideprotectedvirtualinherited |
Wake all tasks currently in the wait list.
Implements stk::ISyncObject.
Definition at line 301 of file stk_helper.h.
References stk::IKernelService::GetInstance(), and stk::IKernelService::Wake().
Referenced by stk::sync::ConditionVariable::NotifyAll_CS(), stk::sync::Event::Pulse(), and stk::sync::Event::Set().
|
inlinestaticinherited |
Wake the first task in the wait list (FIFO order).
| [in] | wlist | Wait list. |
Definition at line 736 of file stk_common.h.
References stk::detail::DListHead< T, TClosedLoop >::GetFirst(), stk::detail::DListCast::ListEntryToParent(), and stk::IWaitObject::Wake().
|
inlineoverrideprotectedvirtualinherited |
Wake the first task in the wait list (FIFO order).
Implements stk::ISyncObject.
Definition at line 296 of file stk_helper.h.
References stk::IKernelService::GetInstance(), and stk::IKernelService::Wake().
Referenced by stk::sync::ConditionVariable::NotifyOne_CS(), stk::sync::Event::Pulse(), stk::sync::Event::Set(), and stk::sync::SemaphoreT< T >::TrySignalLimited().
|
staticconstexpr |
Max count value supported (maximum value of T).
Definition at line 82 of file stk_sync_semaphore.h.
Referenced by stk_sem_create().
|
private |
Internal resource counter.
Definition at line 208 of file stk_sync_semaphore.h.
Referenced by TrySignalLimited(), and WaitEx().
|
private |
Counter max limit.
Definition at line 209 of file stk_sync_semaphore.h.
Referenced by TrySignal(), and TrySignal().
|
privateinherited |
Owning list head, or NULL when the entry is not linked.
Definition at line 191 of file stk_linked_list.h.
|
privateinherited |
Next entry in the list, or NULL (open list boundary) / first entry (closed loop).
Definition at line 192 of file stk_linked_list.h.
|
privateinherited |
Previous entry in the list, or NULL (open list boundary) / last entry (closed loop).
Definition at line 193 of file stk_linked_list.h.
|
protectedinherited |
Tasks blocked on this object.
Definition at line 311 of file stk_helper.h.
Referenced by AddWaitObject(), GetMutableWaitList(), GetWaitList(), stk::sync::Event::Pulse(), RemoveWaitObject(), SyncObjectBase(), stk::sync::SemaphoreT< T >::TrySignalLimited(), stk::sync::FastMutex::Unlock(), stk::sync::Mutex::Unlock(), stk::sync::ConditionVariable::~ConditionVariable(), stk::sync::Event::~Event(), stk::sync::FastMutex::~FastMutex(), and stk::sync::Mutex::~Mutex().