Fixed-priority preemptive scheduling strategy with round-robin arbitration within each priority level. More...

#include <stk_strategy_fpriority.h>

Inheritance diagram for stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >:

Collaboration diagram for stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >:

Public Types
enum	EConfig { WEIGHT_API = 1 , SLEEP_EVENT_API = 1 , DEADLINE_MISSED_API = 0 }
	Compile-time capability flags reported to the kernel. More...
enum	EPriority { PRIORITY_HIGHEST = MAX_PRIORITIES - 1 , PRIORITY_NORMAL = MAX_PRIORITIES / 2 , PRIORITY_LOWEST = 0 }
	Symbolic priority level constants for common use cases. More...

Public Member Functions
	SwitchStrategyFixedPriority ()
	Construct an empty strategy with all priority levels empty, a clear bitmap, and null cursors.
	~SwitchStrategyFixedPriority ()
	Destructor.
void	AddTask (IKernelTask *task)
	Add task to the runnable set at its fixed priority level.
void	RemoveTask (IKernelTask *task)
	Remove task from whichever list it currently occupies.
IKernelTask *	GetNext ()
	Select and return the next task to run.
IKernelTask *	GetFirst () const
	Get the first task in the managed set (used by the kernel for initial scheduling).
size_t	GetSize () const
	Get the total number of tasks managed by this strategy.
void	OnTaskSleep (IKernelTask *task)
	Notification that a task has entered the sleeping state.
void	OnTaskWake (IKernelTask *task)
	Notification that a task has become runnable again.
bool	OnTaskDeadlineMissed (IKernelTask *)
	Not supported, asserts unconditionally.

Protected Types
typedef uint8_t	Priority
	Priority type.

Protected Member Functions
void	AddActive (IKernelTask *task)
	Append a task to its priority level's runnable list and update the bitmap.
void	RemoveActive (IKernelTask *task)
	Remove a task from its priority level's runnable list and update the bitmap/cursor.

Static Protected Member Functions
static __stk_forceinline Priority	GetTaskPriority (IKernelTask *task)
	Get priority from the task..
static __stk_forceinline Priority	GetHighestReadyPriority (uint32_t bitmap)
	Find the index of the highest set bit in bitmap.

Private Member Functions
	STK_NONCOPYABLE_CLASS (SwitchStrategyFixedPriority)

Private Attributes
IKernelTask::ListHeadType	m_tasks [MAX_PRIORITIES]
	Per-priority runnable task lists. m_tasks[i] holds all runnable tasks at priority level i.
IKernelTask::ListHeadType	m_sleep
	Sleeping (blocked) tasks. Priority is retained in GetWeight() and restored on OnTaskWake().
uint32_t	m_ready_bitmap
	Bitmask of non-empty priority levels: bit i is set when m_tasks[i] has at least one runnable task. Updated by AddActive() (bit set) and RemoveActive() (bit cleared on last removal).
IKernelTask *	m_prev [MAX_PRIORITIES]
	Per-priority round-robin cursor. m_prev[i] is the most recently scheduled task at level i, or `nullptr` when level i is empty. GetNext() advances from this position.

Detailed Description

template<uint8_t MAX_PRIORITIES>
class stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >

Fixed-priority preemptive scheduling strategy with round-robin arbitration within each priority level.

Template Parameters

MAX_PRIORITIES Number of distinct priority levels. Must be in the range [1, 32] (enforced by a compile-time assertion). Bit i of the 32-bit m_ready_bitmap represents priority level i. The concrete alias SwitchStrategyFP32 uses MAX_PRIORITIES = 32.

Priority assignment: Each task's priority is read from ITask::GetWeight(), cast to uint8_t, and must be in the range [0, MAX_PRIORITIES - 1]. Tasks do not use the dynamic current-weight mechanism, the static weight value is the priority. Configure a task's priority by overriding ITask::GetWeight() to return the desired level.

Scheduling rules

The highest runnable priority level is always selected. A task at priority N will never run while any task at priority > N is runnable.
Tasks at the same priority level are scheduled in round-robin order (one tick slice each), using a per-level cursor (m_prev[prio]).
Higher numeric value = higher priority. 0 is the lowest, MAX_PRIORITIES - 1 is highest.

Priority detection — O(1) bitmap: m_ready_bitmap is a 32-bit bitmask where bit i is set whenever priority level i has at least one runnable task. GetNext() and GetFirst() locate the highest set bit in O(1) via __builtin_clz (GCC/Clang) or a portable 32->0 scan fallback. The bitmap is kept consistent by AddActive() (bit set) and RemoveActive() (bit cleared on last removal).

Note: Uses the Weight API (WEIGHT_API = 1): GetWeight() is interpreted as the task's fixed priority level. The dynamic weight functions (SetCurrentWeight / GetCurrentWeight) are not used by this strategy.; Requires the kernel Sleep API (SLEEP_EVENT_API = 1): OnTaskSleep() and OnTaskWake() maintain the per-priority runnable lists and keep m_ready_bitmap accurate.

See also: SwitchStrategyFP32, ITaskSwitchStrategy, ITask::GetWeight

Definition at line 58 of file stk_strategy_fpriority.h.

Member Typedef Documentation

◆ Priority

template<uint8_t MAX_PRIORITIES>

typedef uint8_t stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::Priority

protected

Priority type.

Definition at line 250 of file stk_strategy_fpriority.h.

Member Enumeration Documentation

◆ EConfig

template<uint8_t MAX_PRIORITIES>

enum stk::SwitchStrategyFixedPriority::EConfig

Compile-time capability flags reported to the kernel.

Enumerator
WEIGHT_API	This strategy interprets GetWeight() as the task's fixed priority level (0 .. MAX_PRIORITIES - 1). Dynamic weight functions are not used.
SLEEP_EVENT_API	This strategy requires OnTaskSleep() / OnTaskWake() events to maintain per-priority runnable lists and keep `m_ready_bitmap` accurate.
DEADLINE_MISSED_API	This strategy does not use OnTaskDeadlineMissed() events.

Definition at line 64 of file stk_strategy_fpriority.h.

    {
        WEIGHT_API          = 1, 
        SLEEP_EVENT_API     = 1, 
        DEADLINE_MISSED_API = 0  
    };

◆ EPriority

template<uint8_t MAX_PRIORITIES>

enum stk::SwitchStrategyFixedPriority::EPriority

Symbolic priority level constants for common use cases.

Note: Concrete values depend on MAX_PRIORITIES. For SwitchStrategyFP32 (MAX_PRIORITIES = 32): PRIORITY_HIGHEST = 31, PRIORITY_NORMAL = 16, PRIORITY_LOWEST = 0.

Enumerator
PRIORITY_HIGHEST	Highest available priority level (MAX_PRIORITIES - 1).
PRIORITY_NORMAL	Mid-range priority level (MAX_PRIORITIES / 2).
PRIORITY_LOWEST	Lowest priority level. Tasks at this level only run when no higher-priority task is runnable.

Definition at line 76 of file stk_strategy_fpriority.h.

    {
        PRIORITY_HIGHEST = MAX_PRIORITIES - 1, 
        PRIORITY_NORMAL  = MAX_PRIORITIES / 2, 
        PRIORITY_LOWEST  = 0                   
    };

Constructor & Destructor Documentation

◆ SwitchStrategyFixedPriority()

template<uint8_t MAX_PRIORITIES>

stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::SwitchStrategyFixedPriority ( )

inlineexplicit

Construct an empty strategy with all priority levels empty, a clear bitmap, and null cursors.

Note: A compile-time assertion enforces MAX_PRIORITIES <= 32, matching the width of the 32-bit m_ready_bitmap. Instantiating with MAX_PRIORITIES > 32 is a compile error.

Definition at line 87 of file stk_strategy_fpriority.h.

                                           : m_tasks(), m_sleep(), m_ready_bitmap(0U), m_prev()
    {
        STK_STATIC_ASSERT_DESC(MAX_PRIORITIES <= 32U,
            "MAX_PRIORITIES exceeds 32-bit bitmap width");
    }

◆ ~SwitchStrategyFixedPriority()

template<uint8_t MAX_PRIORITIES>

stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::~SwitchStrategyFixedPriority ( )

inline

Destructor.

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

Definition at line 96 of file stk_strategy_fpriority.h.

97 {}

Member Function Documentation

◆ AddActive()

template<uint8_t MAX_PRIORITIES>

void stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::AddActive ( IKernelTask * task )

inlineprotected

Append a task to its priority level's runnable list and update the bitmap.

Parameters

[in] task Task to make runnable.

Note: Appends to the back of m_tasks[prio].; Bitmap and cursor are only updated when the level was previously empty (GetSize() == 1 after LinkBack): m_ready_bitmap bit prio is set and m_prev[prio] is initialised to task. Subsequent additions at the same level leave the cursor untouched (the tail-adjustment in AddTask() handles the cursor for non-first additions).

Definition at line 261 of file stk_strategy_fpriority.h.

    {
        const Priority prio = GetTaskPriority(task);
 
        m_tasks[prio].LinkBack(task);
 
        // init pointer
        if (m_tasks[prio].GetSize() == 1U)
        {
            m_prev[prio] = task;
 
            m_ready_bitmap |= (1U << prio);
        }
    }

Referenced by stk::SwitchStrategyFixedPriority< 32 >::AddTask(), and stk::SwitchStrategyFixedPriority< 32 >::OnTaskWake().

Here is the caller graph for this function:

◆ AddTask()

template<uint8_t MAX_PRIORITIES>

void stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::AddTask ( IKernelTask * task )

inlinevirtual

Add task to the runnable set at its fixed priority level.

Parameters

[in] task Task to add. Must not be NULL and must not already be in any list.

Note: Priority is extracted by casting GetWeight() to uint8_t. The result must be less than MAX_PRIORITIES (asserted); passing a task whose GetWeight() is out of range is a programming error.; Delegates to AddActive() which appends the task to m_tasks[prio], sets m_ready_bitmap bit prio if this is the first task at that level, and initialises m_prev[prio].; Tail-cursor invariant (same as RR): if m_prev[prio] was already pointing at the tail before insertion, it is advanced to the new tail so GetNext() will include the new task in the very next rotation at this priority level.

Implements stk::ITaskSwitchStrategy.

Definition at line 111 of file stk_strategy_fpriority.h.

    {
        STK_ASSERT(task != nullptr);
        STK_ASSERT(task->GetHead() == nullptr);
        STK_ASSERT(GetTaskPriority(task) < MAX_PRIORITIES);
 
        const Priority prio = GetTaskPriority(task);
 
        bool is_tail = (m_prev[prio] == m_tasks[prio].GetLast());
 
        AddActive(task);
 
        // if pointer was pointing to the tail, become a tail
        if (is_tail)
            m_prev[prio] = task;
    }

◆ GetFirst()

template<uint8_t MAX_PRIORITIES>

IKernelTask * stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::GetFirst ( ) const

inlinevirtual

Get the first task in the managed set (used by the kernel for initial scheduling).

Returns: The first task in the highest runnable priority level if any task is runnable (bitmap non-zero); otherwise the first task in m_sleep. Asserts if the combined set is empty (GetSize() == 0).

Note: Uses m_ready_bitmap to determine whether any runnable task exists, consistent with GetNext(). The sleep fallback allows the kernel to identify any task even when all are currently sleeping.

Implements stk::ITaskSwitchStrategy.

Definition at line 178 of file stk_strategy_fpriority.h.

    {
        STK_ASSERT(GetSize() != 0U);
 
        if (m_ready_bitmap == 0U)
            return (*m_sleep.GetFirst());
 
        const Priority prio = GetHighestReadyPriority(m_ready_bitmap);
        return (*m_tasks[prio].GetFirst());
    }

Referenced by stk::SwitchStrategyFixedPriority< 32 >::GetFirst(), and stk::test::TEST().

Here is the caller graph for this function:

◆ GetHighestReadyPriority()

template<uint8_t MAX_PRIORITIES>

__stk_forceinline Priority stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::GetHighestReadyPriority ( uint32_t bitmap )

inlinestaticprotected

Find the index of the highest set bit in bitmap.

Parameters

[in] bitmap Bitmask of ready priority levels. Must not be 0 (behaviour is undefined for __builtin_clz(0); callers must check before calling).

Returns: Index of the most-significant set bit (0-based), which is the highest runnable priority level.

Note: On GCC/Clang: uses __builtin_clz for an O(1) hardware instruction (BSR on x86, CLZ on ARM). On other compilers: falls back to a portable O(32) linear scan from bit 31 down to 0.

Definition at line 327 of file stk_strategy_fpriority.h.

    {
    #if defined(__GNUC__)
        return static_cast<Priority>(31U - __builtin_clz(bitmap));
    #else
        for (int8_t i = 31; i >= 0; --i)
        {
            if (bitmap & (1U << i))
                return static_cast<Priority>(i);
        }
        return 0;
    #endif
    }

Referenced by stk::SwitchStrategyFixedPriority< 32 >::GetFirst(), and stk::SwitchStrategyFixedPriority< 32 >::GetNext().

Here is the caller graph for this function:

◆ GetNext()

template<uint8_t MAX_PRIORITIES>

IKernelTask * stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::GetNext ( )

inlinevirtual

Select and return the next task to run.

Returns: The next task in the highest runnable priority level's round-robin rotation, or nullptr if no runnable tasks exist (m_ready_bitmap == 0, kernel sleeps).

Note: Priority selection is O(1) via GetHighestReadyPriority() on m_ready_bitmap. Within the selected level the cursor (m_prev[prio]) is advanced by one position in the closed-loop list, implementing round-robin within the level.; Tasks at a lower priority are never returned while any higher-priority task has its bitmap bit set — preemption is enforced entirely by the bitmap lookup.

Implements stk::ITaskSwitchStrategy.

Definition at line 157 of file stk_strategy_fpriority.h.

    {
        if (m_ready_bitmap == 0U)
            return nullptr; // idle
 
        const Priority prio = GetHighestReadyPriority(m_ready_bitmap);
 
        IKernelTask *ret = (*m_prev[prio]->GetNext());
        m_prev[prio] = ret;
 
        return ret;
    }

◆ GetSize()

template<uint8_t MAX_PRIORITIES>

size_t stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::GetSize ( ) const

inlinevirtual

Get the total number of tasks managed by this strategy.

Returns: Sum of tasks across all priority levels in m_tasks plus tasks in m_sleep.

Note: O(MAX_PRIORITIES): iterates all priority levels to accumulate the count. Unlike the RR and SWRR strategies this is not O(1).

Implements stk::ITaskSwitchStrategy.

Definition at line 194 of file stk_strategy_fpriority.h.

    {
        size_t total = m_sleep.GetSize();
        for (Priority i = 0U; i < MAX_PRIORITIES; i += 1U)
            total += m_tasks[i].GetSize();
 
        return total;
    }

Referenced by stk::SwitchStrategyFixedPriority< 32 >::AddActive(), stk::SwitchStrategyFixedPriority< 32 >::GetFirst(), stk::SwitchStrategyFixedPriority< 32 >::GetSize(), and stk::SwitchStrategyFixedPriority< 32 >::RemoveTask().

Here is the caller graph for this function:

◆ GetTaskPriority()

template<uint8_t MAX_PRIORITIES>

__stk_forceinline Priority stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::GetTaskPriority ( IKernelTask * task )

inlinestaticprotected

Get priority from the task..

Parameters

[in] task Pointer to the task. Priority is read from GetWeight().

Returns: Priority level.

Definition at line 313 of file stk_strategy_fpriority.h.

    {
        return static_cast<Priority>(task->GetWeight());
    }

Referenced by stk::SwitchStrategyFixedPriority< 32 >::AddActive(), stk::SwitchStrategyFixedPriority< 32 >::AddTask(), and stk::SwitchStrategyFixedPriority< 32 >::RemoveActive().

Here is the caller graph for this function:

◆ OnTaskDeadlineMissed()

template<uint8_t MAX_PRIORITIES>

bool stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::OnTaskDeadlineMissed ( IKernelTask * )

inlinevirtual

Not supported, asserts unconditionally.

Note: This strategy uses DEADLINE_MISSED_API = 0. See OnTaskDeadlineMissed() for rationale.

Implements stk::ITaskSwitchStrategy.

Definition at line 241 of file stk_strategy_fpriority.h.

    {
        // Budget Overrun API unsupported
        STK_ASSERT(false);
        return false;
    }

◆ OnTaskSleep()

template<uint8_t MAX_PRIORITIES>

void stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::OnTaskSleep ( IKernelTask * task )

inlinevirtual

Notification that a task has entered the sleeping state.

Parameters

[in] task The task that is now sleeping. Must be in m_tasks[priority] (asserted).

Note: Delegates to RemoveActive() which unlinks the task from its priority level list, updates the per-level cursor, and clears bit prio in m_ready_bitmap if this was the last runnable task at that level. Then appends the task to m_sleep.

Implements stk::ITaskSwitchStrategy.

Definition at line 209 of file stk_strategy_fpriority.h.

    {
        STK_ASSERT(task != nullptr);
        STK_ASSERT(task->IsSleeping());
        STK_ASSERT(task->GetHead() == &m_tasks[GetTaskPriority(task)]);
 
        RemoveActive(task);
        m_sleep.LinkBack(task);
    }

◆ OnTaskWake()

template<uint8_t MAX_PRIORITIES>

void stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::OnTaskWake ( IKernelTask * task )

inlinevirtual

Notification that a task has become runnable again.

Parameters

[in] task The task that woke up. Must be in m_sleep (asserted).

Note: Unlinks the task from m_sleep and delegates to AddActive() which appends it to m_tasks[priority] and sets the bitmap bit if the level was empty.; Unlike SwitchStrategySmoothWeightedRoundRobin, no priority boost is applied. The waking task re-enters its natural priority level and waits its turn in the round-robin rotation at that level. Its preemption guarantee is provided solely by its fixed priority relative to other runnable levels.

Implements stk::ITaskSwitchStrategy.

Definition at line 228 of file stk_strategy_fpriority.h.

    {
        STK_ASSERT(task != nullptr);
        STK_ASSERT(!task->IsSleeping());
        STK_ASSERT(task->GetHead() == &m_sleep);
 
        m_sleep.Unlink(task);
        AddActive(task);
    }

◆ RemoveActive()

template<uint8_t MAX_PRIORITIES>

void stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::RemoveActive ( IKernelTask * task )

inlineprotected

Remove a task from its priority level's runnable list and update the bitmap/cursor.

Parameters

[in] task Runnable task to remove.

Note

Cursor update algorithm (same as SwitchStrategyRoundRobin::RemoveActive, applied per priority level):

Capture next = task->GetNext() before unlinking.
If next != task (other tasks remain at this level): set m_prev[prio] = next->GetPrev() so GetNext() returns next without skipping it.
If next == task (last task at this level): set m_prev[prio] = NULL and clear bit prio in m_ready_bitmap. GetNext() will then select the next highest set bit, falling through to a lower priority level.

Definition at line 288 of file stk_strategy_fpriority.h.

    {
        const Priority prio = GetTaskPriority(task);
        IKernelTask *next = (*task->GetNext());
 
        m_tasks[prio].Unlink(task);
 
        // update pointer
        if (next != task)
        {
            m_prev[prio] = (*next->GetPrev());
        }
        else
        {
            m_prev[prio] = nullptr;
 
            // this will cause a switch to a lower priority task list
            m_ready_bitmap &= ~(1U << prio);
        }
    }

Referenced by stk::SwitchStrategyFixedPriority< 32 >::OnTaskSleep(), and stk::SwitchStrategyFixedPriority< 32 >::RemoveTask().

Here is the caller graph for this function:

◆ RemoveTask()

template<uint8_t MAX_PRIORITIES>

void stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::RemoveTask ( IKernelTask * task )

inlinevirtual

Remove task from whichever list it currently occupies.

Parameters

[in] task Task to remove. Must not be NULL and must belong to either m_tasks[priority] or m_sleep (asserted).

Note: Dispatch checks m_sleep first (reversed from the RR/SWRR pattern). If sleeping, simply unlinks from m_sleep. If runnable, delegates to RemoveActive() which also updates the cursor and clears the bitmap bit if the priority level becomes empty.

Implements stk::ITaskSwitchStrategy.

Definition at line 136 of file stk_strategy_fpriority.h.

    {
        STK_ASSERT(task != nullptr);
        STK_ASSERT(GetSize() != 0U);
        STK_ASSERT((task->GetHead() == &m_tasks[GetTaskPriority(task)]) || (task->GetHead() == &m_sleep));
 
        if (task->GetHead() == &m_sleep)
            m_sleep.Unlink(task);
        else
            RemoveActive(task);
    }

◆ STK_NONCOPYABLE_CLASS()

template<uint8_t MAX_PRIORITIES>

stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::STK_NONCOPYABLE_CLASS ( SwitchStrategyFixedPriority< MAX_PRIORITIES > )

private

Member Data Documentation

◆ m_prev

template<uint8_t MAX_PRIORITIES>

IKernelTask* stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::m_prev[MAX_PRIORITIES]

private

Per-priority round-robin cursor. m_prev[i] is the most recently scheduled task at level i, or nullptr when level i is empty. GetNext() advances from this position.

Definition at line 347 of file stk_strategy_fpriority.h.

◆ m_ready_bitmap

template<uint8_t MAX_PRIORITIES>

uint32_t stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::m_ready_bitmap

private

Bitmask of non-empty priority levels: bit i is set when m_tasks[i] has at least one runnable task. Updated by AddActive() (bit set) and RemoveActive() (bit cleared on last removal).

Definition at line 346 of file stk_strategy_fpriority.h.

◆ m_sleep

template<uint8_t MAX_PRIORITIES>

IKernelTask::ListHeadType stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::m_sleep

private

Sleeping (blocked) tasks. Priority is retained in GetWeight() and restored on OnTaskWake().

Definition at line 345 of file stk_strategy_fpriority.h.

◆ m_tasks

template<uint8_t MAX_PRIORITIES>

IKernelTask::ListHeadType stk::SwitchStrategyFixedPriority< MAX_PRIORITIES >::m_tasks[MAX_PRIORITIES]

private

Per-priority runnable task lists. m_tasks[i] holds all runnable tasks at priority level i.

Definition at line 344 of file stk_strategy_fpriority.h.

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

stk_strategy_fpriority.h

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Priority

Member Enumeration Documentation

◆ EConfig

◆ EPriority

Constructor & Destructor Documentation

◆ SwitchStrategyFixedPriority()

◆ ~SwitchStrategyFixedPriority()

Member Function Documentation

◆ AddActive()

◆ AddTask()

◆ GetFirst()

◆ GetHighestReadyPriority()

◆ GetNext()

◆ GetSize()

◆ GetTaskPriority()

◆ OnTaskDeadlineMissed()

◆ OnTaskSleep()

◆ OnTaskWake()

◆ RemoveActive()

◆ RemoveTask()

◆ STK_NONCOPYABLE_CLASS()

Member Data Documentation

◆ m_prev

◆ m_ready_bitmap

◆ m_sleep

◆ m_tasks