Zen API
 All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
kStatus kThread_SetPriority ( kThread  thread,
kThreadPriorityClass  priorityClass,
k32s  priorityOffset 
)

Sets the priority associated with the thread.

Thread priorities are specified by providing a priority class and priority offset. The class determines the general category of thread behavior: Low, Normal, or High priority. Signed priority offsets can be used to specify more granular priority distinctions within a priority class. Positive numeric priority offsets represent higher logical priorities, negative priority offsets represent lower logical priorities; offset zero represents the default priority within a class. Minimum and maximum priority offsets within each class vary according to the capabilities of the underlying operating system. Priority support is provided on a best-effort basis; if the OS refuses the specified priority configuration, it will not be reported as an error.

The Normal priority class should be used by default. Normal threads cannot be starved by other Normal threads; as such, it is safe to use priority offsets within this class to tune performance. For operating systems that offer only strict priority-based scheduling, the Normal class will have a single priority level (offset zero). For systems where thread execution times can be weighted without the potential for starvation (e.g., Linux CFS), the Normal class will support a range of priorities.

The Low priority class can be used for non-critical tasks that should receive CPU time only when there are no Normal or High priority tasks available to run. For systems that offer priority-based scheduling, the Low priority class will normally offer multiple distinct levels. This priority class should be used with caution, due to the potential for starvation of Low priority tasks by Normal or High priority tasks. It is strongly recommended to avoid using negative priority offsets within the Low priority class, as such threads may interfere with normal system operation on embedded systems.

The High priority class can be used for time-critical tasks that should preempt Normal and Low priority threads. For systems that offer priority-based scheduling, the High priority class will normally offer multiple distinct priority levels. This class should be used with caution due to the potential for High priority tasks to starve Normal and Low priority tasks. In particular, it is strongly recommended to avoid positive priority offsets within the High priority class, as such threads are likely to interfere with critical system functions. Valid uses of High priority threads are rare; soft-realtime hardware support is the most common use case.

This method can be called before or after starting the thread.

Parameters
threadThread object.
priorityClassThread priority class (Low, Normal, High).
priorityOffsetSigned priority offset; a higher offset represents a higher priority within class.
Returns
Operation status.
See also
kThread_MinPriorityClass, kThread_MaxPriorityClass, kThread_MinPriorityOffset, kThread_MaxPriorityOffset