SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
stk::ISyncObject Class Referenceabstract

Synchronization object interface. More...

#include <stk_common.h>

Inheritance diagram for stk::ISyncObject:
Collaboration diagram for stk::ISyncObject:

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

virtual void AddWaitObject (IWaitObject *wobj)=0
 Called by kernel when a new task starts waiting on this event.
virtual void RemoveWaitObject (IWaitObject *wobj)=0
 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.
virtual const IWaitObject::ListHeadType & GetWaitList () const =0
 Get list of tasks blocked on this object.
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).

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

 ~ISyncObject ()=default
 Destructor.
virtual void WakeOne ()=0
 Wake the first task in the wait list (FIFO order).
virtual void WakeAll ()=0
 Wake all tasks currently in the wait list.
virtual IWaitObject::ListHeadType & GetMutableWaitList ()=0
 Get list of tasks blocked on this object.

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

Friends

class IKernelService
class tz::nsec::detail::CmseISyncObjectWrapper

Detailed Description

Synchronization object interface.

Pure contract that the kernel programs against. Carries no wait-list storage of its own so that alternative backings (e.g. a cross-domain wrapper such as tz::nsec::detail::CmseISyncObjectWrapper) can implement this interface without inheriting an unused/incompatible wait list.

See also
SyncObjectBase for the default, storage-owning implementation used by the built-in primitives.

Definition at line 658 of file stk_common.h.

Member Typedef Documentation

◆ DLEntryType

typedef DListEntry<ISyncObject, TClosedLoop> stk::detail::DListEntry< ISyncObject, 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<ISyncObject, TClosedLoop> stk::detail::DListEntry< ISyncObject, TClosedLoop >::DLHeadType
inherited

Convenience alias for the corresponding list head type.

Definition at line 80 of file stk_linked_list.h.

◆ ListEntryType

List entry type of ISyncObject elements.

Definition at line 672 of file stk_common.h.

◆ ListHeadType

List head type for ISyncObject elements.

Definition at line 667 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.

70{ DLEntryTag = 1 };
Intrusive doubly-linked list node. Embed this as a base class in any object (T) that needs to partici...

Constructor & Destructor Documentation

◆ ~ISyncObject()

stk::ISyncObject::~ISyncObject ( )
protecteddefault

Destructor.

Note
Protected by design. Prevents unsafe polymorphic delete.

Member Function Documentation

◆ AddWaitObject() [1/2]

virtual void stk::ISyncObject::AddWaitObject ( IWaitObject * wobj)
pure virtual

Called by kernel when a new task starts waiting on this event.

Parameters
[in]wobjWait object representing blocked task.
Note
Must be called inside the critical section (see hw::CriticalSection, sync::ScopedCrticalSection).

Implemented in stk::SyncObjectBase.

◆ AddWaitObject() [2/2]

void stk::ISyncObject::AddWaitObject ( IWaitObject::ListHeadType & wlist,
IWaitObject * wobj )
inlinestatic

Called by kernel when a new task starts waiting on this event.

Parameters
[in]wlistWait list.
[in]wobjWait object representing blocked task.
Note
Utility for AddWaitObject and ARM TrustZone support.

Definition at line 679 of file stk_common.h.

680 {
681 STK_ASSERT(wobj->GetHead() == nullptr);
682 wlist.LinkBack(wobj);
683 }
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532

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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ FindWeightHigherThan()

Weight stk::ISyncObject::FindWeightHigherThan ( Weight comp) const
inline

Find higher weight within linked wait objects.

Implementation of ISyncObject::FindWeightHigherThan, see ISyncObject. Placed here as it depends on GetUserTaskFromTid.

Parameters
[in]compWeight to compare with.
Returns
Higher weight value than comp, or NO_WEIGHT if there is no object with a higher weight.
Note
Must be called inside the critical section (see hw::CriticalSection, sync::ScopedCrticalSection).

Definition at line 349 of file stk_helper.h.

350{
351 Weight max_weight = NO_WEIGHT;
352 const IWaitObject *itr = detail::DListCast::ListEntryToParent<const IWaitObject>(GetWaitList().GetFirst());
353
354 while (itr != nullptr)
355 {
356 const Weight w = GetUserTaskFromTid(itr->GetTid())->GetWeight();
357 if (w > max_weight)
358 {
359 max_weight = w;
360 }
361
363 }
364
365 return ((max_weight > comp) ? max_weight : NO_WEIGHT);
366}
ITask * GetUserTaskFromTid(TId task_id) noexcept
Get task instance from its identifier.
Definition stk_arch.h:784
static constexpr Weight NO_WEIGHT
Weight value: weight is not set.
Definition stk_common.h:285
int32_t Weight
Weight value (aka priority).
Definition stk_common.h:236
virtual const IWaitObject::ListHeadType & GetWaitList() const =0
Get list of tasks blocked on this object.
virtual Weight GetWeight() const
Get static base weight of the task.
Definition stk_common.h:997
static __stk_forceinline TTargetType * ListEntryToParent(TSourceType *const lentry)
Casts an intrusive list entry to the concrete type that derives from it.

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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GetFirstWaiterTid()

TId stk::ISyncObject::GetFirstWaiterTid ( ) const
inline

Get id of the task which is first in the wait list (FIFO order), i.e. the one that WakeOne() would wake next.

Returns
TId of the first waiter, or TID_NONE if no tasks are currently waiting.
Note
Read-only introspection for diagnostics / telemetry.
The result is a snapshot: call inside the critical section (see hw::CriticalSection, sync::ScopedCrticalSection) if the list may change concurrently.
See also
GetWaitList

Definition at line 777 of file stk_common.h.

778 {
779 const IWaitObject *const obj = detail::DListCast::ListEntryToParent<const IWaitObject>(
780 GetWaitList().GetFirst());
781
782 return ((obj != nullptr) ? obj->GetTid() : TID_NONE);
783 }
static constexpr TId TID_NONE
Reserved task/thread id representing zero/none thread id.
Definition stk_common.h:268

References stk::IWaitObject::GetTid(), GetWaitList(), stk::detail::DListCast::ListEntryToParent(), and stk::TID_NONE.

Here is the call graph for this function:

◆ GetHead()

DLHeadType * stk::detail::DListEntry< ISyncObject, 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.

85{ return m_head; }

Referenced by stk::SyncObjectBase::~SyncObjectBase().

Here is the caller graph for this function:

◆ GetMutableWaitList()

virtual IWaitObject::ListHeadType & stk::ISyncObject::GetMutableWaitList ( )
protectedpure virtual

Get list of tasks blocked on this object.

Implemented in stk::SyncObjectBase.

Referenced by stk::IKernelService::GetMutableWaitList(), and Tick().

Here is the caller graph for this function:

◆ GetNext()

DLEntryType * stk::detail::DListEntry< ISyncObject, TClosedLoop >::GetNext ( )
inlineinherited

Get the next entry in the list.

Returns
Next entry. In an open 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.

96{ return m_next; }

◆ GetPrev()

DLEntryType * stk::detail::DListEntry< ISyncObject, TClosedLoop >::GetPrev ( )
inlineinherited

Get the previous entry in the list.

Returns
Previous entry. In an open 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.

106{ return m_prev; }

◆ GetWaitList()

virtual const IWaitObject::ListHeadType & stk::ISyncObject::GetWaitList ( ) const
pure virtual

Get list of tasks blocked on this object.

Note
Read-only access for diagnostics / telemetry.
The result is a snapshot: call inside the critical section (see hw::CriticalSection, sync::ScopedCrticalSection) if the list may change concurrently.

Implemented in stk::SyncObjectBase.

Referenced by FindWeightHigherThan(), and GetFirstWaiterTid().

Here is the caller graph for this function:

◆ IsLinked()

bool stk::detail::DListEntry< ISyncObject, 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 115 of file stk_linked_list.h.

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

◆ Link()

void stk::detail::DListEntry< ISyncObject, TClosedLoop >::Link ( DLHeadType * head,
DLEntryType * next,
DLEntryType * prev )
inlineprivateinherited

Wire this entry into a list between prev and next.

Parameters
[in]headThe owning DListHead. Stored as a back-pointer for IsLinked() and ownership checks.
[in]nextThe entry that will follow this one, or NULL if this becomes the last entry.
[in]prevThe 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 150 of file stk_linked_list.h.

151 {
152 m_head = head;
153 m_next = next;
154 m_prev = prev;
155
156 if (m_prev != nullptr)
157 {
158 m_prev->m_next = this;
159 }
160
161 if (m_next != nullptr)
162 {
163 m_next->m_prev = this;
164 }
165 }
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).

◆ operator const ISyncObject *()

stk::detail::DListEntry< ISyncObject, TClosedLoop >::operator const ISyncObject * ( ) 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 129 of file stk_linked_list.h.

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

◆ operator ISyncObject *()

stk::detail::DListEntry< ISyncObject, TClosedLoop >::operator ISyncObject* ( )
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 122 of file stk_linked_list.h.

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

◆ RemoveWaitObject() [1/2]

virtual void stk::ISyncObject::RemoveWaitObject ( IWaitObject * wobj)
pure virtual

Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.).

Parameters
[in]wobjWait object to remove from the wait list.
Note
Must be called inside the critical section (see hw::CriticalSection, sync::ScopedCrticalSection).

Implemented in stk::sync::Event, and stk::SyncObjectBase.

◆ RemoveWaitObject() [2/2]

void stk::ISyncObject::RemoveWaitObject ( IWaitObject::ListHeadType & wlist,
IWaitObject * wobj )
inlinestatic

Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.).

Parameters
[in]wlistWait list.
[in]wobjWait object to remove from the wait list.
Note
Utility for RemoveWaitObject and ARM TrustZone support.

Definition at line 696 of file stk_common.h.

697 {
698 STK_ASSERT(wobj->GetHead() == &wlist);
699 wlist.Unlink(wobj);
700 }

References stk::detail::DListEntry< T, TClosedLoop >::GetHead(), STK_ASSERT, and stk::detail::DListHead< T, TClosedLoop >::Unlink().

Referenced by stk::SyncObjectBase::RemoveWaitObject().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ Tick()

bool stk::ISyncObject::Tick ( Timeout elapsed_ticks)
inlinevirtual

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.

Parameters
[in]elapsed_ticksNumber 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.
Returns
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.
Note
When this method returns 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().
Does not need to be called inside critical section.

Definition at line 315 of file stk_helper.h.

316{
318
319 // note: ScopedCriticalSection usage
320 //
321 // Single-core: no critical section needed - Tick() runs from the tick ISR,
322 // which cannot be re-entered on the local core.
323 //
324 // Multi-core: critical section is required because the tick handler on
325 // each core may call Tick() concurrently for the same sync object,
326 // and ISyncObject::Tick() is not re-entrant.
327#if (STK_ARCH_CPU_COUNT > 1)
328 const hw::CriticalSection::ScopedLock cs_;
329#endif
330
331 IWaitObject *itr = detail::DListCast::ListEntryToParent<IWaitObject>(wlist.GetFirst());
332
333 while (itr != nullptr)
334 {
335 IWaitObject *const next = detail::DListCast::ListEntryToParent<IWaitObject>(itr->GetNext());
336
337 if (!itr->Tick(elapsed_ticks))
338 {
339 itr->Wake(true);
340 }
341
342 itr = next;
343 }
344
345 return !wlist.IsEmpty();
346}
DLHeadType ListHeadType
List head type for IWaitObject elements.
Definition stk_common.h:548
virtual IWaitObject::ListHeadType & GetMutableWaitList()=0
Get list of tasks blocked on this object.

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().

Here is the call graph for this function:

◆ Unlink()

void stk::detail::DListEntry< ISyncObject, 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 174 of file stk_linked_list.h.

175 {
176 if (m_prev != nullptr)
177 {
179 }
180
181 if (m_next != nullptr)
182 {
184 }
185
186 m_head = nullptr;
187 m_next = nullptr;
188 m_prev = nullptr;
189 }

◆ WakeAll() [1/2]

virtual void stk::ISyncObject::WakeAll ( )
protectedpure virtual

Wake all tasks currently in the wait list.

Note
Each woken task is notified with timeout=false, indicating a successful signal (not a timeout expiry).
Does nothing if no tasks are currently waiting.
Must be called inside the critical section (see hw::CriticalSection, sync::ScopedCrticalSection).

Implemented in stk::SyncObjectBase.

Referenced by stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Wake().

Here is the caller graph for this function:

◆ WakeAll() [2/2]

void stk::ISyncObject::WakeAll ( IWaitObject::ListHeadType & wlist)
inlinestatic

Wake all tasks currently in the wait list.

Parameters
[in]wlistWait list.
Note
Each woken task is notified with timeout=false, indicating a successful signal (not a timeout expiry).
Does nothing if no tasks are currently waiting.
Utility for WakeAll and ARM TrustZone support.

Definition at line 752 of file stk_common.h.

753 {
754 for (IWaitObject *obj = detail::DListCast::ListEntryToParent<IWaitObject>(wlist.GetFirst());
755 obj != nullptr;
757 {
758 obj->Wake(false);
759 }
760 }

References stk::detail::DListHead< T, TClosedLoop >::GetFirst(), and stk::detail::DListCast::ListEntryToParent().

Here is the call graph for this function:

◆ WakeOne() [1/2]

virtual void stk::ISyncObject::WakeOne ( )
protectedpure virtual

Wake the first task in the wait list (FIFO order).

Note
The woken task is notified with timeout=false, indicating a successful signal (not a timeout expiry).
Does nothing if no tasks are currently waiting.
Must be called inside the critical section (see hw::CriticalSection, sync::ScopedCrticalSection).

Implemented in stk::SyncObjectBase.

Referenced by stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelService::Wake().

Here is the caller graph for this function:

◆ WakeOne() [2/2]

void stk::ISyncObject::WakeOne ( IWaitObject::ListHeadType & wlist)
inlinestatic

Wake the first task in the wait list (FIFO order).

Parameters
[in]wlistWait list.
Note
The woken task is notified with timeout=false, indicating a successful signal (not a timeout expiry).
Does nothing if no tasks are currently waiting.
Utility for WakeOne and ARM TrustZone support.

Definition at line 736 of file stk_common.h.

737 {
738 IWaitObject *const obj = detail::DListCast::ListEntryToParent<IWaitObject>(wlist.GetFirst());
739 if (obj != nullptr)
740 {
741 obj->Wake(false);
742 }
743 }

References stk::detail::DListHead< T, TClosedLoop >::GetFirst(), stk::detail::DListCast::ListEntryToParent(), and stk::IWaitObject::Wake().

Here is the call graph for this function:

◆ IKernelService

friend class IKernelService
friend

Definition at line 660 of file stk_common.h.

References IKernelService.

Referenced by IKernelService.

◆ tz::nsec::detail::CmseISyncObjectWrapper

friend class tz::nsec::detail::CmseISyncObjectWrapper
friend

Member Data Documentation

◆ m_head

DLHeadType* stk::detail::DListEntry< ISyncObject, TClosedLoop >::m_head
privateinherited

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

Definition at line 191 of file stk_linked_list.h.

◆ m_next

DLEntryType* stk::detail::DListEntry< ISyncObject, TClosedLoop >::m_next
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.

◆ m_prev

DLEntryType* stk::detail::DListEntry< ISyncObject, TClosedLoop >::m_prev
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.


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