OSTaskChangePrio

Description

When creating a task (see OSTaskCreate()), you specify the priority of the task being created. In most cases, it is not necessary to change the priority of the task at run time. However, it is sometimes useful to do so, and OSTaskChangePrio() allows this to take place.

If the task is ready-to-run, OSTaskChangePrio() simply changes the position of the task in µC/OS-III’s ready list. If the task is waiting on an event, OSTaskChangePrio() will change the position of the task in the pend list of the corresponding object, so that the pend list remains sorted by priority.

Because µC/OS-III supports multiple tasks at the same priority, there are no restrictions on the priority that a task can have, except that task priority zero (0) is reserved by µC/OS-III, and priority OS_PRIO_MAX-1 is used by the idle task.

Note that a task priority cannot be changed from an ISR.

Files

os.h/os_task.c

Prototype

void  OSTaskChangePrio (OS_TCB   *p_tcb,
                        OS_PRIO   prio_new,
                        OS_ERR   *p_err)

Arguments

p_tcb

is a pointer to the OS_TCB of the task for which the priority is being changed. If you pass a NULL pointer, the priority of the current task is changed.

prio_new

is the new task’s priority. This value must never be set to OS_CFG_PRIO_MAX-1, or higher and you must not use priority 0 since they are reserved for µC/OS-III.

p_err

is a pointer to a variable that will receive an error code:

OS_ERR_NONE

If the task’s priority is changed.

OS_ERR_OS_NOT_RUNNING

If OS_CFG_INVALID_OS_CALLS_CHK_EN is set to DEF_ENABLED in os_cfg.h: if µC/OS-III is not running yet.

OS_ERR_PRIO_INVALID

If the priority of the task specified is invalid. By specifying a priority greater than or equal to OS_PRIO_MAX-1, or 0 or the same priority in use by another kernel task.

OS_ERR_STATE_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if the task is in an invalid state.

OS_ERR_TASK_CHANGE_PRIO_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if attempting to change the task’s priority from an ISR.

Returned Value

None

Required Configuration

OS_CFG_TASK_CHANGE_PRIO_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.

Callers

Application.

Notes/Warnings

1. The new priority must be available.

Example Usage

          OS_TCB  MyTaskTCB;
           
           
          void TaskX (void *p_arg)
          {
              OS_ERR  err;
           
           
              while (DEF_ON) {
                  :
                  :
                  OSTaskChangePrio(&MyTaskTCB,     /* Change the priority of "MyTask" to 10 */
                                    10,           
                                   &err);
                  /* Check "err" */
                  :
                  :
              }
          }