OSFlagDel

Description

Deletes an event flag group. This function should be used with care since multiple tasks may be relying on the presence of the event flag group. Generally, before deleting an event flag group, first delete all of the tasks that access the event flag group. Also, it is recommended that the user not delete kernel objects at run time.

Files

os.h/os_flag.c

Prototype

OS_OBJ_QTY  OSFlagDel (OS_FLAG_GRP  *p_grp,
                       OS_OPT        opt,
                       OS_ERR       *p_err);

Arguments

p_grp

is a pointer to the event flag group to delete.

opt

specifies whether the user wants to delete the event flag group only if there are no pending tasks (OS_OPT_DEL_NO_PEND), or whether the event flag group should always be deleted regardless of whether or not tasks are pending (OS_OPT_DEL_ALWAYS). In this case, all pending task are readied.

p_err

is a pointer to a variable used to hold an error code. The error code can be one of the following:

OS_ERR_NONE

If the call is successful and the event flag group has been deleted.

OS_ERR_DEL_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if the user attempts to delete an event flag group from an ISR.

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_OBJ_PTR_NULL

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_grp is a NULL pointer.

OS_ERR_OBJ_TYPE

If OS_CFG_OBJ_TYPE_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_grp is not pointing to an event flag group.

OS_ERR_OPT_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if the user does not specify one of the options mentioned in the opt argument.

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_TASK_WAITING

If one or more tasks are waiting on the event flag group and OS_OPT_DEL_NO_PEND is specified.

Returned Values

0 if no task was waiting on the event flag group, or an error occurs.

> 0 if one or more tasks waiting on the event flag group are now readied and informed

Required Configuration

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

Callers

Application.

Notes/Warnings

  1. You should use this call with care as other tasks might expect the presence of the event flag group.

Example Usage

OSFlagDel() example usage
          OS_FLAG_GRP  EngineStatusFlags;
           
           
          void Task (void *p_arg)
          {
              OS_ERR      err;
              OS_OBJ_QTY  qty;
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  qty = OSFlagDel(&EngineStatusFlags,
                                  OS_OPT_DEL_ALWAYS,
                                  &err);
                  /* Check "err" */
                  :
                  :
              }
          }