stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject Class Reference

Concrete implementation of IWaitObject, embedded in each KernelTask slot. More...

#include <stk.h>

Inheritance diagram for stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject:

Collaboration diagram for stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject:

Classes
class	WaitRequest
	Payload stored in the sync object's kernel-side list entry while a task is waiting. More...

Public Types
enum	EState : uint8_t {   STATE_NONE = 0U ,   STATE_WAIT ,   STATE_SIGNALED ,   STATE_TIMEOUT ,   STATE_CANCELLED }
	State of the WaitObject. More...
typedef DLHeadType	ListHeadType
	List head type for IWaitObject elements.
typedef DLEntryType	ListEntryType
	List entry type of IWaitObject elements.
enum
	A tag for type-safe casts done by CastListEntryToParent. More...
typedef DListEntry< IWaitObject, TClosedLoop >	DLEntryType
	Convenience alias for this entry type. Used to avoid repeating the full template spelling.
typedef DListHead< IWaitObject, TClosedLoop >	DLHeadType
	Convenience alias for the corresponding list head type.

Public Member Functions
	WaitObject ()
	~WaitObject ()=default
	Destructor.
TId	GetTid () const override
	Get the TId of the task that owns this wait object.
EState	GetState () const override
	Get current state.
bool	IsWaiting () const
	Check if busy with waiting.
EWaitResult	GetWaitResult () const
	Get wait result.
void	ClearState ()
	Clear state.
void	Wake (bool timeout) override
	Wake the waiting task (called by ISyncObject when it signals).
bool	Tick (Timeout elapsed_ticks) override
	Advance the timeout countdown by a number of ticks.
void	SetupWait (ISyncObject *sync_obj, Timeout timeout)
	Configure and arm this wait object for a new wait operation.
void	CancelNoWake ()
	Cancel an in-progress wait without waking the owning task.
void	Cancel ()
	Cancel an in-progress wait and wake the owning task early.
bool	CancelIfWaiting ()
	Cancel an in-progress wait and wake the owning task early if was waiting.
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 IWaitObject * ()
	Implicit conversion to a mutable pointer to the host object (T).
	operator const IWaitObject * () const
	Implicit conversion to a const pointer to the host object (T).

Public Attributes
KernelTask *	m_task
	Back-pointer to the owning KernelTask. Set once at construction; never changes.
ISyncObject *	m_sync_obj
	Sync object this wait is registered with, or NULL when not waiting.
Timeout	m_time_wait
	Ticks remaining until timeout. Decremented each tick; WAIT_INFINITE means no timeout.
volatile EState	m_state
	State of the object, see WaitObject::EState.

Private Member Functions
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
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).

Detailed Description

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>
class stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject

Concrete implementation of IWaitObject, embedded in each KernelTask slot.

Note

Allocated only when TMode includes KERNEL_SYNC. Zero-size otherwise.

One WaitObject per KernelTask, the back-pointer m_task is wired at KernelTask construction and never changes.

Definition at line 524 of file stk.h.

Member Typedef Documentation

DLEntryType

typedef DListEntry<IWaitObject, TClosedLoop> stk::util::DListEntry< IWaitObject, TClosedLoop >::DLEntryType

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.

DLHeadType

typedef DListHead<IWaitObject, TClosedLoop> stk::util::DListEntry< IWaitObject, TClosedLoop >::DLHeadType

inherited

Convenience alias for the corresponding list head type.

Definition at line 80 of file stk_linked_list.h.

ListEntryType

typedef DLEntryType stk::IWaitObject::ListEntryType

inherited

List entry type of IWaitObject elements.

Definition at line 507 of file stk_common.h.

ListHeadType

typedef DLHeadType stk::IWaitObject::ListHeadType

inherited

List head type for IWaitObject elements.

Definition at line 502 of file stk_common.h.

Member Enumeration Documentation

anonymous enum

anonymous enum

inherited

A tag for type-safe casts done by CastListEntryToParent.

See also

CastListEntryToParent.

Definition at line 70 of file stk_linked_list.h.

{ DLEntryTag = 1 };

EState

enum stk::IWaitObject::EState : uint8_t

inherited

State of the WaitObject.

Enumerator
STATE_NONE
STATE_WAIT	Wait is active.
STATE_SIGNALED	Wake signaled.
STATE_TIMEOUT	Wait expired due to timeout rather than a Wake() signal.
STATE_CANCELLED	Wait was cancelled via Cancel() rather than Wake()/timeout.

Definition at line 512 of file stk_common.h.

    {
        STATE_NONE = 0U,
        STATE_WAIT,      
        STATE_SIGNALED,  
        STATE_TIMEOUT,   
        STATE_CANCELLED  
    };

Constructor & Destructor Documentation

WaitObject()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::WaitObject ( )

inlineexplicit

Definition at line 526 of file stk.h.

                                  : m_task(nullptr), m_sync_obj(nullptr), m_time_wait(NO_WAIT),
                m_state(STATE_NONE)
            {}

References m_state, m_sync_obj, m_task, m_time_wait, stk::NO_WAIT, and stk::IWaitObject::STATE_NONE.

~WaitObject()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::~WaitObject ( )

default

Destructor.

Note

MISRA deviation: [STK-DEV-005] Rule 10-3-2.

References STK_VIRT_DTOR.

Member Function Documentation

Cancel()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::Cancel ( )

inline

Cancel an in-progress wait and wake the owning task early.

Note

Used by IKernel::CancelTaskWait() to interrupt a task blocked in OnTaskWait(), e.g. for cancellable I/O or shutdown sequences. Unlike CancelNoWake(), this DOES wake the task - the task is not being torn down, it needs to legitimately resume execution and observe the result via IsCanceled().

Sets m_canceled instead of m_timeout, so the caller can distinguish a cancelled wait (WAIT_RESULT_CANCELED) from a genuine timeout or signal.

Caller (IKernel::CancelTaskWait()) is responsible for checking IsWaiting() before calling this - it asserts rather than no-op, mirroring Wake().

Definition at line 682 of file stk.h.

            {
                STK_ASSERT(IsWaiting());
 
                m_state     = STATE_CANCELLED;
                m_time_wait = NO_WAIT;
 
                m_sync_obj->RemoveWaitObject(this);
                m_sync_obj = nullptr;
 
                m_task->Wake();
            }

References IsWaiting(), m_state, m_sync_obj, m_task, m_time_wait, stk::NO_WAIT, stk::IWaitObject::STATE_CANCELLED, and STK_ASSERT.

Referenced by CancelIfWaiting().

Here is the call graph for this function:

Here is the caller graph for this function:

CancelIfWaiting()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

bool stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::CancelIfWaiting ( )

inline

Cancel an in-progress wait and wake the owning task early if was waiting.

Returns

true if cancelled active waiting, false otherwise.

See also

Cancel, IsWaiting

Definition at line 699 of file stk.h.

            {
                const bool was_waiting = IsWaiting();
                if (was_waiting)
                {
                    Cancel();
                }
 
                return was_waiting;
            }

References Cancel(), and IsWaiting().

Here is the call graph for this function:

CancelNoWake()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::CancelNoWake ( )

inline

Cancel an in-progress wait without waking the owning task.

Note

Used when the owning task is being forcibly removed (see KernelTask::ScheduleRemoval) while blocked on a synchronization object. Unlike Wake(), this does not touch m_task's sleep state or set m_timeout - the task is being torn down and will never observe the wait result.

No-op if not currently waiting.

Definition at line 660 of file stk.h.

            {
                if (IsWaiting())
                {
                    m_state = STATE_CANCELLED;
 
                    m_sync_obj->RemoveWaitObject(this);
                    m_sync_obj = nullptr;
                }
            }

References IsWaiting(), m_state, m_sync_obj, and stk::IWaitObject::STATE_CANCELLED.

Here is the call graph for this function:

ClearState()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::ClearState ( )

inline

Clear state.

See also

OnTaskWait

Definition at line 586 of file stk.h.

            {
                STK_ASSERT(!IsWaiting());
 
                m_state = STATE_NONE;
            }

References IsWaiting(), m_state, stk::IWaitObject::STATE_NONE, and STK_ASSERT.

Here is the call graph for this function:

GetHead()

DLHeadType * stk::util::DListEntry< IWaitObject, TClosedLoop >::GetHead ( )

inlineinherited

Get the list head this entry currently belongs to.

Returns

Pointer to the owning DListHead, or NULL if the entry is not linked.

Definition at line 85 of file stk_linked_list.h.

{ return m_head; }

GetNext()

DLEntryType * stk::util::DListEntry< IWaitObject, TClosedLoop >::GetNext ( )

inlineinherited

Get the next entry in the list.

Returns

Pointer to the next DListEntry, or NULL if this is the last entry (open list) or the first entry (closed loop, where next wraps to first).

Note

In a closed loop (TClosedLoop == true) this pointer is never NULL when the entry is linked.

Definition at line 98 of file stk_linked_list.h.

{ return m_next; }

GetPrev()

DLEntryType * stk::util::DListEntry< IWaitObject, TClosedLoop >::GetPrev ( )

inlineinherited

Get the previous entry in the list.

Returns

Pointer to the previous DListEntry, or NULL if this is the first entry (open list) or the last entry (closed loop, where prev wraps to last).

Note

In a closed loop (TClosedLoop == true) this pointer is never NULL when the entry is linked.

Definition at line 114 of file stk_linked_list.h.

{ return m_prev; }

GetState()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

EState stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::GetState ( ) const

inlineoverridevirtual

Get current state.

Returns

State value.

See also

EState

Implements stk::IWaitObject.

Definition at line 554 of file stk.h.

{ return m_state; }

References m_state.

Referenced by GetWaitResult().

Here is the caller graph for this function:

GetTid()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

TId stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::GetTid ( ) const

inlineoverridevirtual

Get the TId of the task that owns this wait object.

Returns

TId of m_task.

Implements stk::IWaitObject.

Definition at line 548 of file stk.h.

{ return m_task->GetTid(); }

References m_task.

GetWaitResult()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

EWaitResult stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::GetWaitResult ( ) const

inline

Get wait result.

Returns

Result value.

See also

OnTaskWait, EWaitResult

Definition at line 565 of file stk.h.

            {
                STK_ASSERT(!IsWaiting());
 
                switch (GetState())
                {
                case STATE_TIMEOUT:
                    return WAIT_RESULT_TIMEOUT;
                case STATE_CANCELLED:
                    return WAIT_RESULT_CANCELED;
                default: {
                    STK_ASSERT(m_state != STATE_NONE);
                    STK_ASSERT(m_state != STATE_WAIT);
                    STK_ASSERT(m_state == STATE_SIGNALED);
                    return WAIT_RESULT_SIGNAL; }
                }
            }

References GetState(), IsWaiting(), m_state, stk::IWaitObject::STATE_CANCELLED, stk::IWaitObject::STATE_NONE, stk::IWaitObject::STATE_SIGNALED, stk::IWaitObject::STATE_TIMEOUT, stk::IWaitObject::STATE_WAIT, STK_ASSERT, stk::WAIT_RESULT_CANCELED, stk::WAIT_RESULT_SIGNAL, and stk::WAIT_RESULT_TIMEOUT.

Here is the call graph for this function:

IsLinked()

bool stk::util::DListEntry< IWaitObject, TClosedLoop >::IsLinked ( ) const

inlineinherited

Check whether this entry is currently a member of any list.

Returns

true if linked (m_head != NULL); false otherwise.

Definition at line 127 of file stk_linked_list.h.

{ return (GetHead() != nullptr); }

IsWaiting()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

bool stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::IsWaiting ( ) const

inline

Check if busy with waiting.

Returns

true if waiting, false if not.

Definition at line 559 of file stk.h.

{ return (m_sync_obj != nullptr); }

References m_sync_obj.

Referenced by Cancel(), CancelIfWaiting(), CancelNoWake(), ClearState(), stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::GetSleepTicks(), GetWaitResult(), SetupWait(), and Wake().

Here is the caller graph for this function:

Link()

void stk::util::DListEntry< IWaitObject, TClosedLoop >::Link ( DLHeadType * head, DLEntryType * next, DLEntryType * prev )

inlineprivateinherited

Wire this entry into a list between prev and next.

Parameters

[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.

Note

Called exclusively by DListHead::Link(). Assumes the entry is not currently linked. Updates the neighbours' forward/back pointers to splice this entry in.

Definition at line 162 of file stk_linked_list.h.

    {
        m_head = head;
        m_next = next;
        m_prev = prev;
 
        if (m_prev != nullptr)
        {
            m_prev->m_next = this;
        }
 
        if (m_next != nullptr)
        {
            m_next->m_prev = this;
        }
    }

operator const IWaitObject *()

stk::util::DListEntry< IWaitObject, TClosedLoop >::operator const IWaitObject * ( ) const

inlineinherited

Implicit conversion to a const pointer to the host object (T).

Note

Safe because T must derive from DListEntry<T, TClosedLoop>. Eliminates the need for explicit static_cast at call sites.

MISRA deviation: [STK-DEV-004] Rule 5-2-x.

Definition at line 141 of file stk_linked_list.h.

{ return static_cast<const T *>(this); }

operator IWaitObject *()

stk::util::DListEntry< IWaitObject, TClosedLoop >::operator IWaitObject* ( )

inlineinherited

Implicit conversion to a mutable pointer to the host object (T).

Note

Safe because T must derive from DListEntry<T, TClosedLoop>. Eliminates the need for explicit static_cast at call sites.

MISRA deviation: [STK-DEV-004] Rule 5-2-x.

Definition at line 134 of file stk_linked_list.h.

{ return static_cast<T *>(this); }

SetupWait()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::SetupWait ( ISyncObject * sync_obj, Timeout timeout )

inline

Configure and arm this wait object for a new wait operation.

Parameters

[in]	sync_obj	The synchronization object to wait on. Must not already have this wait object registered (asserted).
[in]	timeout	Maximum ticks to wait, or WAIT_INFINITE for no timeout.

Note

Registers this object with sync_obj's wait list via AddWaitObject(). Must be paired with a matching Wake() or timeout expiry.

Definition at line 642 of file stk.h.

            {
                STK_ASSERT(!IsWaiting());
 
                m_sync_obj  = sync_obj;
                m_time_wait = timeout;
                m_state     = STATE_WAIT;
 
                sync_obj->AddWaitObject(this);
            }

References stk::ISyncObject::AddWaitObject(), IsWaiting(), m_state, m_sync_obj, m_time_wait, stk::IWaitObject::STATE_WAIT, and STK_ASSERT.

Here is the call graph for this function:

Tick()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

bool stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::Tick ( Timeout elapsed_ticks )

inlineoverridevirtual

Advance the timeout countdown by a number of ticks.

Returns

true if the wait is still active (not yet timed out), false if the timeout just expired (caller should stop ticking this object).

Note

Called by UpdateSyncObjects() each kernel tick. WAIT_INFINITE waits never time out and always return true.

Implements stk::IWaitObject.

Definition at line 617 of file stk.h.

            {
                if (m_time_wait != WAIT_INFINITE)
                {
                    if (m_state == STATE_WAIT)
                    {                  
                        m_time_wait -= elapsed_ticks;
 
                        if (m_time_wait <= NO_WAIT)
                        {
                            m_state = STATE_TIMEOUT;
                        }
                    }
                }
 
                return (m_state == STATE_WAIT);
            }

References m_state, m_time_wait, stk::NO_WAIT, stk::IWaitObject::STATE_TIMEOUT, stk::IWaitObject::STATE_WAIT, and stk::WAIT_INFINITE.

Unlink()

void stk::util::DListEntry< IWaitObject, TClosedLoop >::Unlink ( )

inlineprivateinherited

Remove this entry from its current list.

Note

Called exclusively by DListHead::Unlink(). Patches the neighbours' pointers to bridge over this entry, then clears m_head, m_next, and m_prev to NULL so the entry is in a clean unlinked state.

Does not update DListHead::m_count or m_first / m_last — those are the responsibility of the calling DListHead::Unlink().

Definition at line 186 of file stk_linked_list.h.

    {
        if (m_prev != nullptr)
        {
            m_prev->m_next = m_next;
        }
 
        if (m_next != nullptr)
        {
            m_next->m_prev = m_prev;
        }
 
        m_head = nullptr;
        m_next = nullptr;
        m_prev = nullptr;
    }

Wake()

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

void stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::Wake ( bool timeout )

inlineoverridevirtual

Wake the waiting task (called by ISyncObject when it signals).

Parameters

[in]

timeout

true if woken because the timeout expired, false if signalled.

Note

Clears m_time_wait, records the timeout flag, removes this object from m_sync_obj's wait list, nulls m_sync_obj, then calls m_task->Wake().

Implements stk::IWaitObject.

Definition at line 598 of file stk.h.

            {
                STK_ASSERT(IsWaiting());
 
                m_state     = (timeout ? STATE_TIMEOUT : STATE_SIGNALED);
                m_time_wait = NO_WAIT;
 
                m_sync_obj->RemoveWaitObject(this);
                m_sync_obj = nullptr;
 
                return m_task->Wake();
            }

References IsWaiting(), m_state, m_sync_obj, m_task, m_time_wait, stk::NO_WAIT, stk::IWaitObject::STATE_SIGNALED, stk::IWaitObject::STATE_TIMEOUT, and STK_ASSERT.

Here is the call graph for this function:

Member Data Documentation

m_head

DLHeadType* stk::util::DListEntry< IWaitObject, TClosedLoop >::m_head

privateinherited

Owning list head, or NULL when the entry is not linked.

Definition at line 203 of file stk_linked_list.h.

m_next

DLEntryType* stk::util::DListEntry< IWaitObject, TClosedLoop >::m_next

privateinherited

Next entry in the list, or NULL (open list boundary) / first entry (closed loop).

Definition at line 204 of file stk_linked_list.h.

m_prev

DLEntryType* stk::util::DListEntry< IWaitObject, TClosedLoop >::m_prev

privateinherited

Previous entry in the list, or NULL (open list boundary) / last entry (closed loop).

Definition at line 205 of file stk_linked_list.h.

m_state

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

volatile EState stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::m_state

State of the object, see WaitObject::EState.

Definition at line 713 of file stk.h.

Referenced by Cancel(), CancelNoWake(), ClearState(), GetState(), GetWaitResult(), SetupWait(), Tick(), WaitObject(), and Wake().

m_sync_obj

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

ISyncObject* stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::m_sync_obj

Sync object this wait is registered with, or NULL when not waiting.

Definition at line 711 of file stk.h.

Referenced by Cancel(), CancelNoWake(), IsWaiting(), SetupWait(), WaitObject(), and Wake().

m_task

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

KernelTask* stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::m_task

Back-pointer to the owning KernelTask. Set once at construction; never changes.

Definition at line 710 of file stk.h.

Referenced by Cancel(), GetTid(), WaitObject(), and Wake().

m_time_wait

template<uint8_t TMode, uint32_t TSize, class TStrategy, class TPlatform>

Timeout stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::m_time_wait

Ticks remaining until timeout. Decremented each tick; WAIT_INFINITE means no timeout.

Definition at line 712 of file stk.h.

Referenced by Cancel(), stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::GetSleepTicks(), SetupWait(), Tick(), WaitObject(), and Wake().

---

The documentation for this class was generated from the following file:

• stk.h