OSTaskSuspend

Description

OSTaskSuspend() suspends (or blocks) execution of a task unconditionally. The calling task may be suspended by specifying a NULL pointer for p_tcb, or simply by passing the address of its OS_TCB. In this case, another task needs to resume the suspended task. If the current task is suspended, rescheduling occurs, and µC/OS-III runs the next highest priority task ready-to-run. The only way to resume a suspended task is to call OSTaskResume().

Task suspension is additive, which means that if the task being suspended is delayed until N ticks expire, the task is resumed only when both the time expires and the suspension is removed. Also, if the suspended task is waiting for a semaphore and the semaphore is signaled, the task is removed from the semaphore wait list (if it is the highest-priority task waiting for the semaphore), but execution is not resumed until the suspension is removed.

The user can “nest” suspension of a task by calling OSTaskSuspend() and therefore it is important to call OSTaskResume() an equivalent number of times to resume the task. If suspending a task five times, it is necessary to unsuspend the same task five times to remove the suspension of the task.

Files

os.h/os_task.c

Prototype

void   OSTaskSuspend (OS_TCB  *p_tcb,
                      OS_ERR  *p_err)

Arguments

p_tcb

is a pointer to the TCB of the task the user is suspending. A NULL pointer indicates suspension of the calling task.

p_err

is a pointer to a variable that will contain an error code returned by this function.

OS_ERR_NONE

If the call was successful and the desired task was suspended.

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_SCHED_LOCKED

If attempting to suspend a task while the scheduler is locked.

OS_ERR_STATE_INVALID

If attempting to suspend a task that is in an invalid state.

OS_ERR_TASK_SUSPEND_CTR_OVF

If the nesting counter overflowed.

OS_ERR_TASK_SUSPEND_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if the function is called from an ISR.

OS_ERR_TASK_SUSPEND_IDLE

If attempting to suspend the idle task. This is not allowed since the idle task must always exist.

OS_ERR_TASK_SUSPEND_INT_HANDLER

If OS_CFG_ISR_POST_DEFERRED_EN is set to DEF_ENABLED in os_cfg.h: If attempting to suspend the ISR handler task. This is not allowed since the ISR handler task is a µC/OS-III internal task.

Returned Value

None

Required Configuration

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

Callers

Application.

Notes/Warnings

1. OSTaskSuspend() and OSTaskResume() must be used in pairs.
2. A suspended task can only be resumed by OSTaskResume().

Example Usage

          void TaskX (void *p_arg)
          {
              OS_ERR  err;
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  OSTaskSuspend((OS_TCB *)0,
                                &err);       /* Suspend current task                       */
                  /* Check "err" */
                  :
                  :
              }
          }