![]() |
SuperTinyKernel™ RTOS 1.06.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. More...
#include <stk_sync_semaphore.h>
Public Member Functions | |
| Semaphore (uint16_t initial_count=0U, uint16_t max_count=COUNT_MAX) | |
| Constructor. | |
| ~Semaphore () | |
| Destructor. | |
| 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). | |
| uint16_t | GetCount () const |
| Get current counter value. | |
| void | SetTraceName (const char *name) |
| Set name. | |
| const char * | GetTraceName () const |
| Get name. | |
Static Public Attributes | |
| static const uint16_t | COUNT_MAX = 0xFFFEU |
| Max count value supported. | |
Private Types | |
| typedef DLHeadType | ListHeadType |
| List head type for ISyncObject elements. | |
| typedef DLEntryType | ListEntryType |
| List entry type of ISyncObject elements. | |
| 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. | |
Private Member Functions | |
| Semaphore (const Semaphore &)=delete | |
| Semaphore & | operator= (const Semaphore &)=delete |
| virtual void | AddWaitObject (IWaitObject *wobj) |
| Called by kernel when a new task starts waiting on this event. | |
| virtual void | RemoveWaitObject (IWaitObject *wobj) |
| Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.). | |
| 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. | |
| void | WakeOne () |
| Wake the first task in the wait list (FIFO order). | |
| void | WakeAll () |
| Wake all tasks currently in the wait list. | |
| 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 | 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 | |
| uint16_t | m_count |
| Internal resource counter. | |
| uint16_t | m_count_max |
| Counter max limit. | |
| IWaitObject::ListHeadType | m_wait_list |
| tasks blocked on this object | |
| 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.
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.
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 55 of file stk_sync_semaphore.h.
|
inherited |
Convenience alias for this entry type. Used to avoid repeating the full template spelling.
Definition at line 70 of file stk_linked_list.h.
|
inherited |
Convenience alias for the corresponding list head type.
Definition at line 75 of file stk_linked_list.h.
|
inherited |
List entry type of ISyncObject elements.
Definition at line 441 of file stk_common.h.
|
inherited |
List head type for ISyncObject elements.
Definition at line 436 of file stk_common.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 71 of file stk_sync_semaphore.h.
References COUNT_MAX, m_count, m_count_max, and STK_ASSERT.
Referenced by operator=().
|
inline |
Destructor.
Definition at line 83 of file stk_sync_semaphore.h.
References stk::ISyncObject::m_wait_list, STK_ASSERT, and STK_VIRT_DTOR.
|
privatedelete |
|
inlinevirtualinherited |
Called by kernel when a new task starts waiting on this event.
| [in] | wobj | Wait object representing blocked task. |
Definition at line 447 of file stk_common.h.
References stk::util::DListEntry< T, TClosedLoop >::GetHead(), m_wait_list, and STK_ASSERT.
Referenced by stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::SetupWait().
Find higher weight within linked wait objects.
Implementation of ISyncObject::Tick, see ISyncObject. Placed here as it depends on GetUserTaskFromTid.
| [in] | comp | Weight to compare with. |
Definition at line 214 of file stk_helper.h.
References stk::util::DListEntry< T, TClosedLoop >::GetNext(), stk::IWaitObject::GetTid(), stk::GetUserTaskFromTid(), stk::ITask::GetWeight(), m_wait_list, and stk::NO_WEIGHT.
Referenced by stk::Kernel< stk::KERNEL_DYNAMIC|stk::KERNEL_SYNC|stk::KERNEL_TICKLESS, 16U, stk::SwitchStrategyFP32, stk::PlatformDefault >::OnRestoreWeight(), and stk::sync::Mutex::Unlock().
|
inline |
Get current counter value.
Definition at line 117 of file stk_sync_semaphore.h.
References m_count.
Referenced by osSemaphoreGetCount(), stk_sem_get_count(), uxSemaphoreGetCount(), xQueueAddToSet(), xQueueRemoveFromSet(), xSemaphoreGive(), xSemaphoreGiveFromISR(), and xTaskNotifyStateClearIndexed().
|
inlineinherited |
Get the list head this entry currently belongs to.
NULL if the entry is not linked. Definition at line 80 of file stk_linked_list.h.
|
inlineinherited |
Get the next entry in the list.
NULL if this is the last entry (open list) or the first entry (closed loop, where next wraps to first). TClosedLoop == true) this pointer is never NULL when the entry is linked. Definition at line 93 of file stk_linked_list.h.
|
inlineinherited |
Get the previous entry in the list.
NULL if this is the first entry (open list) or the last entry (closed loop, where prev wraps to last). TClosedLoop == true) this pointer is never NULL when the entry is linked. Definition at line 109 of file stk_linked_list.h.
|
inlineinherited |
Get name.
NULL if not set or if STK_SYNC_DEBUG_NAMES is 0. Definition at line 406 of file stk_common.h.
|
inlineinherited |
Check whether this entry is currently a member of any list.
true if linked (m_head != NULL); false otherwise. Definition at line 122 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 157 of file stk_linked_list.h.
|
inlineinherited |
Implicit conversion to a const pointer to the host object (T).
Definition at line 136 of file stk_linked_list.h.
|
inlineinherited |
Implicit conversion to a mutable pointer to the host object (T).
Definition at line 129 of file stk_linked_list.h.
|
inlinevirtualinherited |
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. |
Reimplemented in stk::sync::Event.
Definition at line 457 of file stk_common.h.
References stk::util::DListEntry< T, TClosedLoop >::GetHead(), m_wait_list, and STK_ASSERT.
Referenced by stk::sync::Event::RemoveWaitObject().
|
inlineinherited |
Set name.
| [in] | name | Null-terminated string or NULL. |
Definition at line 394 of file stk_common.h.
References STK_UNUSED.
Referenced by stk::memory::BlockMemoryPool::BlockMemoryPool(), and stk::memory::BlockMemoryPool::BlockMemoryPool().
|
inline |
Post a signal (increment counter).
Definition at line 164 of file stk_sync_semaphore.h.
References m_count, m_count_max, stk::ISyncObject::m_wait_list, STK_ASSERT, and stk::ISyncObject::WakeOne().
Referenced by stk_sem_signal(), xSemaphoreGive(), xSemaphoreGiveFromISR(), xTaskNotifyAndQueryIndexed(), xTaskNotifyGiveIndexed(), and xTaskNotifyIndexed().
|
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 181 of file stk_helper.h.
References stk::util::DListEntry< T, TClosedLoop >::GetNext(), m_wait_list, stk::IWaitObject::Tick(), and stk::IWaitObject::Wake().
|
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 102 of file stk_sync_semaphore.h.
References stk::NO_WAIT, and Wait().
Referenced by stk_sem_trywait(), xSemaphoreTakeFromISR(), and xTaskNotifyStateClearIndexed().
|
inlineprivateinherited |
Remove this entry from its current list.
Definition at line 181 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. Definition at line 130 of file stk_sync_semaphore.h.
References stk::IKernelService::GetInstance(), stk::hw::IsInsideISR(), stk::IWaitObject::IsTimeout(), m_count, stk::NO_WAIT, STK_ASSERT, and stk::IKernelService::Wait().
Referenced by osSemaphoreAcquire(), stk_sem_wait(), TryWait(), ulTaskNotifyTakeIndexed(), xSemaphoreTake(), and xTaskNotifyWaitIndexed().
|
inlineprotectedinherited |
Wake all tasks currently in the wait list.
Definition at line 516 of file stk_common.h.
References m_wait_list, and stk::IWaitObject::Wake().
Referenced by stk::sync::ConditionVariable::NotifyAll_CS(), stk::sync::Event::Pulse(), and stk::sync::Event::Set().
|
inlineprotectedinherited |
Wake the first task in the wait list (FIFO order).
Definition at line 502 of file stk_common.h.
References m_wait_list, and stk::IWaitObject::Wake().
Referenced by stk::sync::ConditionVariable::NotifyOne_CS(), stk::sync::Event::Pulse(), stk::sync::Event::Set(), and stk::sync::Semaphore::Signal().
|
static |
Max count value supported.
Definition at line 60 of file stk_sync_semaphore.h.
Referenced by osSemaphoreNew(), Semaphore(), stk_sem_create(), xSemaphoreCreateCounting(), xSemaphoreCreateCountingStatic(), xSemaphoreGive(), and xSemaphoreGiveFromISR().
|
private |
Internal resource counter.
Definition at line 122 of file stk_sync_semaphore.h.
Referenced by GetCount(), Semaphore(), Signal(), and Wait().
|
private |
Counter max limit.
Definition at line 123 of file stk_sync_semaphore.h.
Referenced by Semaphore(), and Signal().
|
privateinherited |
Owning list head, or NULL when the entry is not linked.
Definition at line 198 of file stk_linked_list.h.
|
privateinherited |
Next entry in the list, or NULL (open list boundary) / first entry (closed loop).
Definition at line 199 of file stk_linked_list.h.
|
privateinherited |
Previous entry in the list, or NULL (open list boundary) / last entry (closed loop).
Definition at line 200 of file stk_linked_list.h.
|
protectedinherited |
tasks blocked on this object
Definition at line 524 of file stk_common.h.
Referenced by AddWaitObject(), FindWeightHigherThan(), ISyncObject(), stk::sync::Event::Pulse(), RemoveWaitObject(), stk::sync::Semaphore::Signal(), Tick(), stk::sync::Mutex::Unlock(), WakeAll(), WakeOne(), stk::sync::ConditionVariable::~ConditionVariable(), stk::sync::Event::~Event(), stk::sync::Mutex::~Mutex(), and stk::sync::Semaphore::~Semaphore().