This diagnostic routine reads out the list of tasks waiting at a specified RTX semaphore, Event Group or Message Exchange.

int RTX_Wait_Queue ( unsigned int handle,
                     void       far *details,
                     unsigned int     list_size,
                     unsigned int    filter );



Input parameter:   RTX object identifier for a semaphore, Event Group, or Message Exchange whose wait list is desired.


Optional Output parameter:   Pointer to a buffer which will receive objects which can be referenced with the RTX_DETAILS union of structure pointers.   The first object in this list will apply to the RTX object specified by handle . All subsequent reported objects will be RTX_DETAIL_TASK type, one for each task waiting in the queue listed from first to last.   This parameter can be set to NULL in order to receive a return value indicating how large the buffer should be for a subsequent call.


Number of bytes in buffer at details .   If either this value is zero or details is NULL, then no RTX_DETAILS reporting is done and the return value indicates with a negative value how large a buffer will be required for a subsequent call.


Must be one of the following masks to indicate to what type of RTX resource the handle applies:

    RTX_FILT_SEM - For semaphore
    RTX_FILT_EVENT_GROUP - For an Event Group
    RTX_FILT_MSGXCHG - For a Message Exchange

Return Value

Less than zero:   Either details was NULL or more than list_size will be required for reporting the requested data.   In this case, the negative of this return value is the minimum size buffer required for the report.

Equal zero:   Error, most likely the handle did not apply to an RTX resource of the type indicated by filter .

Greater than zero:   Number of RTX_DETAILS structures output to array at details .   The first structure applies to the RTX object referenced by handle .    The subsequent entries are all RTX_DETAIL_TASK type.   The number of task waiting at the queue is equal to this return value minus one.


This diagnostic API is used to determine which tasks are waiting in a queue at an RTX semaphore, Event Group or Message Exchange.   The filter argument must indicate to which type RTX resource the handle argument applies.

Inside this API, the RTX data is collected with the task switching locked.   Interrupts are enabled after inhibiting task switching.   The interrupt mask is restored to the state on entry prior to re-enabling the task switching on return.   Nevertheless, a task switch can occur at the moment task switching is re-enabled here, thereby defeating any interrupt mask set by the caller.

See Also


This library function invokes a RTOS software interrupt. Refer to this RTOS API function's documentation for more details.

Related Topics

RTX API   Overview

Supported since or modified in @CHIP-RTOS version


Supported by @CHIP-RTOS C Library since version


This API List
List of C Libraries
@CHIP-RTOS Main Index

End of document