RTEMS 4.6.0pre5 On-Line Library

Task Manager TASK_SET_PRIORITY - Set task priority

RTEMS C User's Guide

5.4.9: TASK_SET_PRIORITY - Set task priority

CALLING SEQUENCE:

rtems_status_code rtems_task_set_priority(
  rtems_id             id,
  rtems_task_priority  new_priority,
  rtems_task_priority *old_priority
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL - task priority set successfully
RTEMS_INVALID_ID - invalid task id
RTEMS_INVALID_ADDRESS - invalid return argument pointer
RTEMS_INVALID_PRIORITY - invalid task priority

DESCRIPTION:

This directive manipulates the priority of the task specified by id. An id of RTEMS_SELF is used to indicate the calling task. When new_priority is not equal to RTEMS_CURRENT_PRIORITY, the specified task's previous priority is returned in old_priority. When new_priority is RTEMS_CURRENT_PRIORITY, the specified task's current priority is returned in old_priority. Valid priorities range from a high of 1 to a low of 255.

NOTES:

The calling task may be preempted if its preemption mode is enabled and it lowers its own priority or raises another task's priority.

Setting the priority of a global task which does not reside on the local node will generate a request to the remote node to change the priority of the specified task.

If the task specified by id is currently holding any binary semaphores which use the priority inheritance algorithm, then the task's priority cannot be lowered immediately. If the task's priority were lowered immediately, then priority inversion results. The requested lowering of the task's priority will occur when the task has released all priority inheritance binary semaphores. The task's priority can be increased regardless of the task's use of priority inheritance binary semaphores.

RTEMS C User's Guide