Interface for a task switching strategy implementation. More...

#include <stk_common.h>

Inheritance diagram for stk::ITaskSwitchStrategy:

Public Member Functions
virtual void	AddTask (IKernelTask *task)=0
	Add task.
virtual void	RemoveTask (IKernelTask *task)=0
	Remove task.
virtual IKernelTask *	GetFirst ()=0
	Get first task.
virtual IKernelTask *	GetNext ()=0
	Advance the internal iterator and return the next runnable task.
virtual size_t	GetSize () const =0
	Get number of tasks currently managed by this strategy.
virtual void	OnTaskSleep (IKernelTask *task)=0
	Notification that a task has entered sleep/blocked state.
virtual void	OnTaskWake (IKernelTask *task)=0
	Notification that a task is becoming runnable again.
virtual bool	OnTaskYield (IKernelTask *task)
	Notification that the running task called Yield() (non-HRT kernel modes only).
virtual bool	OnTaskTimeSlice (IKernelTask *task)
	Notification that the running task's time slice expired (KERNEL_TIMESLICE only).
virtual bool	OnTaskDeadlineMissed (IKernelTask *task)
	Notification that a task has exceeded its HRT deadline; returns whether the strategy can recover without a hard fault.
virtual void	OnTaskWeightChange (IKernelTask *task, Weight old_weight)
	Notification that a runnable task's scheduling weight has changed.

Protected Member Functions
	~ITaskSwitchStrategy ()=default
	Destructor.

Detailed Description

Interface for a task switching strategy implementation.

Note

Combines the Strategy and Iterator design patterns.

Strategy: concrete subclasses encapsulate the scheduling policy (round-robin, EDF, rate-monotonic, weighted round-robin, etc.) independently of the kernel.
Iterator: GetFirst() and GetNext() expose a stateful forward-iterator over the runnable task set. The cursor is owned by the concrete implementation and is not exposed directly, iteration is therefore not re-entrant.

Implementation must declare the following compile-time constants for reporting its capabilities to the kernel (place inside EConfig enum):

Example:

enum EConfig
{
    WEIGHT_API               = 0, // (1) if strategy needs Weight API of the kernel task, (0) otherwise (see \a IKernelTask and Weight API functions)
    SLEEP_EVENT_API          = 0, // (1) if strategy needs Sleep API events generated by the kernel, (0) otherwise (see \a ITaskSwitchStrategy::OnTaskSleep, \a ITaskSwitchStrategy::OnTaskWake)
    DEADLINE_MISSED_API      = 0, // (1) if strategy implements OnTaskDeadlineMissed() and can absorb HRT deadline overruns, (0) otherwise (see \a ITaskSwitchStrategy::OnTaskDeadlineMissed)
    PRIORITY_INHERITANCE_API = 0, // (1) if strategy expects OnTaskWeightChange() events to support priority inheritance requests
    NOSLEEP_YIELD_API        = 0, // (1) if strategy implements OnTaskYield() and handles Yield() without putting the task to sleep, (0) otherwise (see \a ITaskSwitchStrategy::OnTaskYield)
    TIMESLICE_API            = 0  // (1) if GetNext() is sticky (does not rotate same-priority peers by itself) and OnTaskTimeSlice() rotates them, (0) otherwise (see \a ITaskSwitchStrategy::OnTaskTimeSlice)
};

Definition at line 1391 of file stk_common.h.

Constructor & Destructor Documentation

◆ ~ITaskSwitchStrategy()

stk::ITaskSwitchStrategy::~ITaskSwitchStrategy ( )

protecteddefault

Destructor.

Note: Protected by design. Prevents unsafe polymorphic delete.

Member Function Documentation

◆ AddTask()

virtual void stk::ITaskSwitchStrategy::AddTask ( IKernelTask * task )

pure virtual

Add task.

Note: Kernel tasks are added by the concrete implementation of IKernel.

Parameters

[in] task Pointer to the task to add.

◆ GetFirst()

virtual IKernelTask * stk::ITaskSwitchStrategy::GetFirst ( )

pure virtual

Get first task.

Returns: Pointer to the first task in the managed set, or NULL if no tasks have been added.

◆ GetNext()

virtual IKernelTask * stk::ITaskSwitchStrategy::GetNext ( )

pure virtual

Advance the internal iterator and return the next runnable task.

Returns: Pointer to the next active task to schedule, or NULL if no runnable tasks are available (in which case the kernel transitions to FSM_STATE_SLEEPING).

Note: Implementations maintain an internal cursor. This method is not re-entrant, concurrent calls from multiple contexts are not supported.

◆ GetSize()

virtual size_t stk::ITaskSwitchStrategy::GetSize ( ) const

pure virtual

Get number of tasks currently managed by this strategy.

Returns: Total number of tasks in the set (runnable and idle).

◆ OnTaskDeadlineMissed()

virtual bool stk::ITaskSwitchStrategy::OnTaskDeadlineMissed ( IKernelTask * task )

inlinevirtual

Notification that a task has exceeded its HRT deadline; returns whether the strategy can recover without a hard fault.

Parameters

[in] task The task whose deadline was missed. Must not be nullptr.

Returns: true — the strategy has absorbed the overrun (e.g. by escalating its scheduling mode): the kernel must not call HrtHardFailDeadline() for this tick. false — the strategy cannot recover: the kernel must call HrtHardFailDeadline() as normal.

Note: Budget Overrun API. Called by the kernel from UpdateTaskState() within a tick, after GetNext() has already been called for that tick. Only invoked when DEADLINE_MISSED_API == 1 in the concrete strategy's EConfig. Strategies that set DEADLINE_MISSED_API = 0 do not need to implement this method; the kernel will not call it and will proceed directly to HrtHardFailDeadline().; Returning true carries no implicit side-effects on task sleep state or duration counters — normal tick-driven scheduling remains responsible for those. This call only communicates "do not hard-fault this tick."; The base implementation returns false (unrecoverable), which is the correct default for strategies that do not implement overrun recovery.

Definition at line 1487 of file stk_common.h.

    {
        STK_UNUSED(task);
        return false;
    }

References STK_UNUSED.

◆ OnTaskSleep()

virtual void stk::ITaskSwitchStrategy::OnTaskSleep ( IKernelTask * task )

pure virtual

Notification that a task has entered sleep/blocked state.

Parameters

[in] task Pointer to the sleeping task,

Note: Sleep API. Implementations shall remove the task from runnable set here.

◆ OnTaskTimeSlice()

virtual bool stk::ITaskSwitchStrategy::OnTaskTimeSlice ( IKernelTask * task )

inlinevirtual

Notification that the running task's time slice expired (KERNEL_TIMESLICE only).

Parameters

[in] task Pointer to the running task, currently in the runnable set.

Returns: true if the strategy rotated to a same-priority peer (the following GetNext() returns it); false to keep running the task (no peer, or the task is not eligible for time-slicing).

Note: Unlike OnTaskYield() this must not release preemption-threshold style holds.; Called from the tick handler. Only invoked when TIMESLICE_API == 1.

See also: SwitchStrategyPreemptionThreshold::OnTaskTimeSlice

Reimplemented in stk::SwitchStrategyPreemptionThreshold< MAX_PRIORITIES, TIMESLICE >, stk::SwitchStrategyPreemptionThreshold< 32 >, and stk::SwitchStrategyPreemptionThreshold< 32, true >.

Definition at line 1461 of file stk_common.h.

    {
        STK_UNUSED(task);
        return false;
    }

References STK_UNUSED.

◆ OnTaskWake()

virtual void stk::ITaskSwitchStrategy::OnTaskWake ( IKernelTask * task )

pure virtual

Notification that a task is becoming runnable again.

Parameters

[in] task Pointer to the waking task

Note: Sleep API. Implementations shall re-insert the task into the runnable set here.

◆ OnTaskWeightChange()

virtual void stk::ITaskSwitchStrategy::OnTaskWeightChange	(	IKernelTask *	task,
		Weight	old_weight )

inlinevirtual

Notification that a runnable task's scheduling weight has changed.

Parameters

[in]	task	The task whose weight was just updated via SetWeight().
[in]	old_weight	The previous weight of this task (required to remove it from the priority list belonging to that weight).

Note: Called only for tasks that are currently in the runnable set (not sleeping). The strategy must relink the task to reflect its new weight. For strategies with WEIGHT_API = 0 this is a no-op. For SwitchStrategyFixedPriority it moves the task from its old priority-level list to the new one and updates m_ready_bitmap.; Called from within a ScopedCriticalSection.

Reimplemented in stk::SwitchStrategyFixedPriority< MAX_PRIORITIES, NoSleepYield >, stk::SwitchStrategyFixedPriority< 32 >, stk::SwitchStrategyFixedPriority< 32, true >, stk::SwitchStrategyPreemptionThreshold< MAX_PRIORITIES, TIMESLICE >, stk::SwitchStrategyPreemptionThreshold< 32 >, and stk::SwitchStrategyPreemptionThreshold< 32, true >.

Definition at line 1505 of file stk_common.h.

    {
        STK_UNUSED(task);
        STK_UNUSED(old_weight);
    }

References STK_UNUSED.

◆ OnTaskYield()

virtual bool stk::ITaskSwitchStrategy::OnTaskYield ( IKernelTask * task )

inlinevirtual

Notification that the running task called Yield() (non-HRT kernel modes only).

Parameters

[in] task Pointer to the yielding task, currently in the runnable set.

Returns: true if the strategy handled the yield itself: the task stays runnable (it is NOT put to sleep) and the strategy must arrange for the following GetNext() to return another task according to its own policy; false (default) if the kernel shall perform the legacy yield, i.e. sleep the task for YIELD_TICKS.

Note: Called from within a critical section, in the context of the yielding task.; Never called in KERNEL_HRT mode, where Yield() signals job completion.

See also: SwitchStrategyPreemptionThreshold::OnTaskYield

Definition at line 1446 of file stk_common.h.

    {
        STK_UNUSED(task);
        return false;
    }

References STK_UNUSED.

◆ RemoveTask()

virtual void stk::ITaskSwitchStrategy::RemoveTask ( IKernelTask * task )

pure virtual

Remove task.

Note: Kernel tasks are removed from the concrete implementation of IKernel.

Parameters

[in] task Pointer to the task to remove.

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

stk_common.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~ITaskSwitchStrategy()

Member Function Documentation

◆ AddTask()

◆ GetFirst()

◆ GetNext()

◆ GetSize()

◆ OnTaskDeadlineMissed()

◆ OnTaskSleep()

◆ OnTaskTimeSlice()

◆ OnTaskWake()

◆ OnTaskWeightChange()

◆ OnTaskYield()

◆ RemoveTask()