|
SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
|
Binary synchronization event (signaled / non-signaled) primitive. More...
#include <stk_sync_event.h>
Public Types | |
| 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 | |
| Event (bool manual_reset=false, bool initial_state=false) | |
| Constructor. | |
| ~Event () | |
| Destructor. | |
| bool | Set () |
| Set event to signaled state. | |
| bool | Reset () |
| Reset event to non-signaled state. | |
| EWaitResult | WaitEx (Timeout timeout_ticks=WAIT_INFINITE) |
| Wait until event becomes signaled or the timeout expires, preserving the full wait outcome. | |
| bool | Wait (Timeout timeout_ticks=WAIT_INFINITE) |
| Wait until event becomes signaled or the timeout expires. | |
| bool | TryWait () |
| Poll event state without blocking. | |
| void | Pulse () |
| Pulse event: attempt to release waiters and then reset (Win32 PulseEvent() semantics). | |
| void | AddWaitObject (IWaitObject *wobj) override |
| Called by kernel when a new task starts waiting on this event. | |
| 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. | |
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 | |
| Event (const Event &)=delete | |
| Event & | operator= (const Event &)=delete |
| void | RemoveWaitObject (IWaitObject *wobj) override |
| Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.). | |
| 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 | |
| bool | m_manual_reset |
true = manual-reset event, false = auto-reset | |
| bool | m_signaled |
| current signaled state of the event | |
| 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). | |
Binary synchronization event (signaled / non-signaled) primitive.
Supports two operation modes:
Additionally, supports Pulse(): attempt to release waiters and then reset (Win32 PulseEvent() semantics).
Set() + Reset() patterns when possible.Definition at line 61 of file stk_sync_event.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.
| [in] | manual_reset | If true creates a manual-reset event (stays signaled until explicitly reset). If false (default) creates an auto-reset event. |
| [in] | initial_state | Initial state of the event: true = signaled, false = non-signaled. |
Definition at line 69 of file stk_sync_event.h.
References m_manual_reset, and m_signaled.
Referenced by Event().
|
inline |
Destructor.
Definition at line 78 of file stk_sync_event.h.
References stk::SyncObjectBase::m_wait_list, STK_ASSERT, and STK_VIRT_DTOR.
Referenced by stk::pthread::ReleaseThreadResources().
|
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().
|
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.
|
inline |
Pulse event: attempt to release waiters and then reset (Win32 PulseEvent() semantics).
Set() + Reset() patterns when possible. Definition at line 205 of file stk_sync_event.h.
References m_manual_reset, m_signaled, stk::SyncObjectBase::m_wait_list, stk::SyncObjectBase::WakeAll(), and stk::SyncObjectBase::WakeOne().
Referenced by stk_event_pulse().
|
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().
|
inlineoverrideprivatevirtual |
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 298 of file stk_sync_event.h.
References stk::IWaitObject::GetState(), m_manual_reset, m_signaled, stk::SyncObjectBase::RemoveWaitObject(), and stk::IWaitObject::STATE_SIGNALED.
|
inline |
Reset event to non-signaled state.
true if state was changed from signaled to non-signaled, false if event was already non-signaled. Definition at line 189 of file stk_sync_event.h.
References m_signaled.
Referenced by stk_event_reset().
|
inline |
Set event to signaled state.
true if state was changed from non-signaled to signaled, false if event was already signaled. false. false means the event was already signaled, not that no task woke. Definition at line 158 of file stk_sync_event.h.
References m_manual_reset, m_signaled, stk::SyncObjectBase::WakeAll(), and stk::SyncObjectBase::WakeOne().
Referenced by stk::time::TimerHost::ProcessCommands(), CtrlTask< _AccessMode >::Run(), LedTask< _Priority, _AccessMode >::Run(), and stk_event_set().
|
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().
|
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 |
Poll event state without blocking.
Checks if the event is currently signaled. If signaled, performs the auto-reset (if auto-reset mode is active) and returns immediately without yielding the CPU or entering a wait list.
true if event was signaled at the time of the call, false if event was not signaled. Definition at line 275 of file stk_sync_event.h.
References m_manual_reset, and m_signaled.
Referenced by stk_event_trywait().
|
inlineprivateinherited |
Remove this entry from its current list.
Definition at line 174 of file stk_linked_list.h.
|
inline |
Wait until event becomes signaled or the timeout expires.
| [in] | timeout_ticks | Maximum time to wait (ticks). Use WAIT_INFINITE for no timeout (wait forever). |
NO_WAIT, ISR-unsafe otherwise. true if event was signaled (wait succeeded), false otherwise (timeout, cancellation or NO_WAIT on a non-signaled event). Use WaitEx() to tell these apart. Definition at line 122 of file stk_sync_event.h.
References stk::WAIT_INFINITE, stk::WAIT_RESULT_SIGNAL, and WaitEx().
Referenced by CtrlTask< _AccessMode >::Run(), LedTask< _Priority, _AccessMode >::Run(), and stk_event_wait().
|
inline |
Wait until event becomes signaled or the timeout expires, preserving the full wait outcome.
| [in] | timeout_ticks | Maximum time to wait (ticks). Use WAIT_INFINITE for no timeout (wait forever). |
NO_WAIT, ISR-unsafe otherwise. WAIT_RESULT_SIGNAL if the event was signaled, WAIT_RESULT_TIMEOUT if the event was not signaled and the timeout expired (or NO_WAIT was passed), WAIT_RESULT_CANCELED if the wait was cancelled via IKernel::CancelTaskWait() (the event state is not consumed), WAIT_RESULT_FAIL if the kernel rejected the wait. Definition at line 237 of file stk_sync_event.h.
References stk::IKernelService::GetInstance(), stk::hw::IsInsideISR(), m_manual_reset, m_signaled, stk::NO_WAIT, STK_ASSERT, stk::IKernelService::Wait(), stk::WAIT_RESULT_SIGNAL, and stk::WAIT_RESULT_TIMEOUT.
Referenced by stk::time::TimerHost::Execute(), JoinThread(), stk_event_wait_ex(), and 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().
|
privateinherited |
Owning list head, or NULL when the entry is not linked.
Definition at line 191 of file stk_linked_list.h.
|
private |
true = manual-reset event, false = auto-reset
Definition at line 150 of file stk_sync_event.h.
Referenced by Event(), Pulse(), RemoveWaitObject(), Set(), TryWait(), and WaitEx().
|
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.
|
private |
current signaled state of the event
Definition at line 151 of file stk_sync_event.h.
Referenced by Event(), Pulse(), RemoveWaitObject(), Reset(), Set(), TryWait(), and WaitEx().
|
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().