stk::util::DListEntry< T, TClosedLoop > Class Template Reference

Intrusive doubly-linked list node. Embed this as a base class in any object (T) that needs to participate in a DListHead list. More...

#include <stk_linked_list.h>

Inheritance diagram for stk::util::DListEntry< T, TClosedLoop >:

Collaboration diagram for stk::util::DListEntry< T, TClosedLoop >:

Public Types
enum	{ DLEntryTag = 1 }
	A tag for type-safe casts done by CastListEntryToParent. More...
typedef DListEntry< T, TClosedLoop >	DLEntryType
	Convenience alias for this entry type. Used to avoid repeating the full template spelling.
typedef DListHead< T, TClosedLoop >	DLHeadType
	Convenience alias for the corresponding list head type.

Public Member Functions
	DListEntry ()
	Construct an unlinked entry. All pointers initialized to NULL.
DLHeadType *	GetHead ()
	Get the list head this entry currently belongs to.
const DLHeadType *	GetHead () const
	Get the list head this entry currently belongs to.
DLEntryType *	GetNext ()
	Get the next entry in the list.
const DLEntryType *	GetNext () const
	Get the next entry in the list.
DLEntryType *	GetPrev ()
	Get the previous entry in the list.
const DLEntryType *	GetPrev () const
	Get the previous entry in the list.
bool	IsLinked () const
	Check whether this entry is currently a member of any list.
	operator T* ()
	Implicit conversion to a mutable pointer to the host object (T).
	operator const T * () const
	Implicit conversion to a const pointer to the host object (T).

Protected Member Functions
	~DListEntry ()=default
	Protected non-virtual destructor.

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	DListHead< T, TClosedLoop >

Detailed Description

template<class T, bool TClosedLoop>
class stk::util::DListEntry< T, TClosedLoop >

Intrusive doubly-linked list node. Embed this as a base class in any object (T) that needs to participate in a DListHead list.

Template Parameters

T	The host class that derives from DListEntry. Used by the implicit conversion operators to safely downcast the node pointer back to the host object pointer without a dynamic_cast.
TClosedLoop	When true the list is kept circular (last->next == first and first->prev == last). When false the list is linear (boundary pointers are NULL). Must match the TClosedLoop of the DListHead this entry will be inserted into.

Note

An entry that is not currently in any list has m_head == NULL. Use IsLinked() to test membership before calling any DListHead operation.

A single DListEntry instance may belong to at most one DListHead at a time. Inserting a linked entry into a second list without first removing it from the first will trigger an assertion.

Not thread-safe. The caller is responsible for protecting list operations with a hw::CriticalSection or equivalent.

Definition at line 57 of file stk_linked_list.h.

Member Typedef Documentation

DLEntryType

template<class T, bool TClosedLoop>

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

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

template<class T, bool TClosedLoop>

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

Convenience alias for the corresponding list head type.

Definition at line 80 of file stk_linked_list.h.

Member Enumeration Documentation

anonymous enum

template<class T, bool TClosedLoop>

anonymous enum

A tag for type-safe casts done by CastListEntryToParent.

See also

CastListEntryToParent.

Enumerator
DLEntryTag

Definition at line 70 of file stk_linked_list.h.

{ DLEntryTag = 1 };

Constructor & Destructor Documentation

DListEntry()

template<class T, bool TClosedLoop>

stk::util::DListEntry< T, TClosedLoop >::DListEntry ( )

inlineexplicit

Construct an unlinked entry. All pointers initialized to NULL.

Definition at line 64 of file stk_linked_list.h.

                          : m_head(nullptr), m_next(nullptr), m_prev(nullptr)
    {}

References m_head, m_next, and m_prev.

~DListEntry()

template<class T, bool TClosedLoop>

stk::util::DListEntry< T, TClosedLoop >::~DListEntry ( )

protecteddefault

Protected non-virtual destructor.

Note

Non-virtual by design: adding a vtable pointer would increase the size of every kernel object and pull in the C++ runtime. The consequence is that deleting a DListEntry pointer directly (rather than through the host T pointer) will not invoke the host destructor — do not do this.

An entry should be removed from its list (via DListHead::Unlink) before the host object is destroyed, to keep the list's neighbour pointers consistent.

Member Function Documentation

GetHead() [1/2]

template<class T, bool TClosedLoop>

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

inline

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; }

References m_head.

Referenced by stk::SwitchStrategyEDF::AddTask(), stk::SwitchStrategyFixedPriority< 32 >::AddTask(), stk::SwitchStrategyMonotonic< MSS_TYPE_RATE >::AddTask(), stk::SwitchStrategyRoundRobin::AddTask(), stk::ISyncObject::AddWaitObject(), IsLinked(), stk::SwitchStrategyEDF::OnTaskSleep(), stk::SwitchStrategyFixedPriority< 32 >::OnTaskSleep(), stk::SwitchStrategyRoundRobin::OnTaskSleep(), stk::SwitchStrategySmoothWeightedRoundRobin::OnTaskSleep(), stk::Kernel< stk::KERNEL_DYNAMIC|stk::KERNEL_SYNC|stk::KERNEL_TICKLESS,(16U), stk::SwitchStrategyFP32, stk::PlatformDefault >::OnTaskWait(), stk::SwitchStrategyEDF::OnTaskWake(), stk::SwitchStrategyFixedPriority< 32 >::OnTaskWake(), stk::SwitchStrategyRoundRobin::OnTaskWake(), stk::SwitchStrategySmoothWeightedRoundRobin::OnTaskWake(), stk::SwitchStrategyFixedPriority< 32 >::OnTaskWeightChange(), stk::time::TimerHost::ProcessCommands(), stk::SwitchStrategyEDF::RemoveTask(), stk::SwitchStrategyFixedPriority< 32 >::RemoveTask(), stk::SwitchStrategyMonotonic< MSS_TYPE_RATE >::RemoveTask(), stk::SwitchStrategyRoundRobin::RemoveTask(), stk::SwitchStrategySmoothWeightedRoundRobin::RemoveTask(), stk::ISyncObject::RemoveWaitObject(), and stk::util::DListHead< T, TClosedLoop >::Unlink().

Here is the caller graph for this function:

GetHead() [2/2]

template<class T, bool TClosedLoop>

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

inline

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 90 of file stk_linked_list.h.

{ return m_head; }

References m_head.

GetNext() [1/2]

template<class T, bool TClosedLoop>

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

inline

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; }

References m_next.

Referenced by stk::SwitchStrategyMonotonic< MSS_TYPE_RATE >::AddTask(), stk::ISyncObject::FindWeightHigherThan(), stk::SwitchStrategyEDF::GetNext(), stk::SwitchStrategyMonotonic< MSS_TYPE_RATE >::GetNext(), stk::SwitchStrategyRoundRobin::GetNext(), stk::SwitchStrategySmoothWeightedRoundRobin::GetNext(), stk::SchedulabilityCheck::IsSchedulableWCRT(), stk::util::DListHead< T, TClosedLoop >::Link(), stk::SwitchStrategyFixedPriority< 32 >::RemoveActive(), stk::SwitchStrategyRoundRobin::RemoveActive(), stk::ISyncObject::Tick(), stk::util::DListHead< T, TClosedLoop >::Unlink(), stk::Kernel< stk::KERNEL_DYNAMIC|stk::KERNEL_SYNC|stk::KERNEL_TICKLESS,(16U), stk::SwitchStrategyFP32, stk::PlatformDefault >::UpdateSyncObjects(), and stk::time::TimerHost::UpdateTime().

Here is the caller graph for this function:

GetNext() [2/2]

template<class T, bool TClosedLoop>

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

inline

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 106 of file stk_linked_list.h.

{ return m_next; }

References m_next.

GetPrev() [1/2]

template<class T, bool TClosedLoop>

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

inline

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; }

References m_prev.

Referenced by stk::SwitchStrategyMonotonic< MSS_TYPE_RATE >::AddTask(), stk::util::DListHead< T, TClosedLoop >::Link(), stk::SwitchStrategyFixedPriority< 32 >::RemoveActive(), stk::SwitchStrategyRoundRobin::RemoveActive(), and stk::util::DListHead< T, TClosedLoop >::Unlink().

Here is the caller graph for this function:

GetPrev() [2/2]

template<class T, bool TClosedLoop>

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

inline

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 122 of file stk_linked_list.h.

{ return m_prev; }

References m_prev.

IsLinked()

template<class T, bool TClosedLoop>

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

inline

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); }

References GetHead().

Referenced by stk::util::DListHead< T, TClosedLoop >::Link(), stk::time::TimerHost::ProcessCommands(), and stk::util::DListHead< T, TClosedLoop >::Unlink().

Here is the call graph for this function:

Here is the caller graph for this function:

Link()

template<class T, bool TClosedLoop>

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

inlineprivate

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;
        }
    }

References m_head, m_next, and m_prev.

Referenced by stk::util::DListHead< T, TClosedLoop >::Link().

Here is the caller graph for this function:

operator const T *()

template<class T, bool TClosedLoop>

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

inline

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 T*()

template<class T, bool TClosedLoop>

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

inline

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); }

Unlink()

template<class T, bool TClosedLoop>

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

inlineprivate

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;
    }

References m_head, m_next, and m_prev.

Referenced by stk::util::DListHead< T, TClosedLoop >::Unlink().

Here is the caller graph for this function:

Friends And Related Symbol Documentation

DListHead< T, TClosedLoop >

template<class T, bool TClosedLoop>

friend class DListHead< T, TClosedLoop >

friend

Definition at line 1 of file stk_linked_list.h.

Member Data Documentation

m_head

template<class T, bool TClosedLoop>

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

private

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

Definition at line 203 of file stk_linked_list.h.

Referenced by DListEntry(), GetHead(), GetHead(), Link(), and Unlink().

m_next

template<class T, bool TClosedLoop>

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

private

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

Definition at line 204 of file stk_linked_list.h.

Referenced by DListEntry(), GetNext(), GetNext(), Link(), and Unlink().

m_prev

template<class T, bool TClosedLoop>

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

private

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

Definition at line 205 of file stk_linked_list.h.

Referenced by DListEntry(), GetPrev(), GetPrev(), Link(), and Unlink().

---

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

• stk_linked_list.h