OSSemPendAbort
Description
Aborts and readies any task currently waiting on a semaphore. This function should be used to fault-abort the wait on the semaphore, rather than to normally signal the semaphore via OSSemPost()
.
Files
os.h/os_sem.c
Prototype
OS_OBJ_QTY OSSemPendAbort (OS_SEM *p_sem, OS_OPT opt, OS_ERR *p_err)
Arguments
p_sem
is a pointer to the semaphore for which pend(s) need to be aborted.
opt
determines the type of abort performed.
OS_OPT_PEND_ABORT_1
Aborts the pend of only the highest-priority task waiting on the semaphore.
OS_OPT_PEND_ABORT_ALL
Aborts the pend of all the tasks waiting on the semaphore.
OS_OPT_POST_NO_SCHED
Specifies that the scheduler should not be called, even if the pend of a higher-priority task has been aborted. Scheduling will need to occur from another function.
You would use this option if the task calling OSSemPendAbort()
will be doing additional pend aborts, reschedule takes place when finished, and multiple pend aborts are to take effect simultaneously.
p_err
Is a pointer to a variable that holds an error code:
OS_ERR_NONE
At least one task waiting on the semaphore was readied and informed of the aborted wait. Check the return value for the number of tasks whose wait on the semaphore was aborted.
OS_ERR_OBJ_PTR_NULL
If OS_CFG_ARG_CHK_EN
is set to DEF_ENABLED
in os_cfg.h
: if
p_sem
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_sem
is not pointing to a semaphore.
OS_ERR_OPT_INVALID
If OS_CFG_ARG_CHK_EN
is set to DEF_ENABLED
in os_cfg.h
: if
an invalid option is specified.
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_PEND_ABORT_ISR
If OS_CFG_CALLED_FROM_ISR_CHK_EN
set to DEF_ENABLED
in os_cfg.h
: if you called this function from an ISR.
OS_ERR_PEND_ABORT_NONE
If no tasks were aborted because no task was waiting.
Returned Value
OSSemPendAbort()
returns the number of tasks made ready-to-run by this function. Zero indicates that no tasks were pending on the semaphore and therefore, or an error.
Required Configuration
OS_CFG_SEM_EN
and OS_CFG_SEM_PEND_ABORT_EN
must be enabled in os_cfg.h
. Refer to µC-OS-III Configuration Manual.
Callers
Application.
Notes/Warnings
- Semaphores must be created before they are used.
Example Usage
OS_SEM SwSem; void CommTask(void *p_arg) { OS_ERR err; OS_OBJ_QTY nbr_tasks; (void)&p_arg; while (DEF_ON) { : : nbr_tasks = OSSemPendAbort(&SwSem, OS_OPT_PEND_ABORT_ALL, &err); /* Check "err" */ : : } }