OSTaskDel

Description

When a task is no longer needed, it can be deleted. Deleting a task does not mean that the code is removed, but that the task code is no longer managed by µC/OS-III. OSTaskDel() can be used when creating a task that will only run once. In this case, the task must not return but instead call OSTaskDel((OS_TCB *)0, &err) which specifies to µC/OS-III to delete the currently running task.

A task may also delete another task by specifying to OSTaskDel() the address of the OS_TCB of the task to delete.

Once a task is deleted, its OS_TCB and stack may be reused to create another task. This assumes that the task’s stack requirement of the new task is satisfied by the stack size of the deleted task.

Even though µC/OS-III allows the user to delete tasks at run time, it is recommend that such actions be avoided. Why? Because a task can “own” resources that are shared with other tasks. Deleting the task that owns resource(s) without first relinquishing the resources could lead to strange behaviors and possible deadlocks.

Files

os.h/os_task.c

Prototype

void  OSTaskDel (OS_TCB  *p_tcb,
                 OS_ERR  *p_err)

Arguments

p_tcb

is a pointer to the TCB of the task to delete or, you can pass a NULL pointer to specify that the calling task delete itself. If deleting the calling task, the scheduler will be invoked so that the next highest-priority task is executed.

p_err

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

OS_ERR_NONE

'p_err' gets set to OS_ERR_NONE before OSSched() to allow the returned error code to be monitored (by another task) even for a task that is deleting itself. In this case, p_err must point to a global variable that can be accessed by that other task and, you should initialize that variable to OS_ERR_TASK_RUNNING prior to deleting the task.

OS_ERR_ILLEGAL_DEL_RUN_TIME

If OS_SAFETY_CRITICAL_IEC61508 is defined: you called this after calling OSStart() and thus you are no longer allowed to delete kernel objects.

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_STATE_INVALID

If the task is in an invalid state.

OS_ERR_TASK_DEL_IDLE

If attempting to delete the idle task.

OS_ERR_TASK_DEL_INVALID

If attempting to delete the ISR Handler task while OS_CFG_ISR_POST_DEFERRED_EN is set to DEF_ENABLED.

OS_ERR_TASK_DEL_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if you called OSTaskDel() from an ISR.

Returned Value

None

Required Configuration

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

Callers

Application.

Notes/Warnings

1. OSTaskDel() verifies that the user is not attempting to delete the µC/OS-III idle task and the ISR handler task.
2. Be careful when deleting a task that owns resources.

Example Usage

          OS_TCB  MyTaskTCB;
           
           
          void TaskX (void *p_arg)
          {
              OS_ERR  err;
           
           
              while (DEF_ON) {
                  :
                  :
                  OSTaskDel(&MyTaskTCB,
                            &err);
                  /* Check "err" */
                  :
                  :
              }
          }