QUE_dequeue
Application Program Interface
2-341
C Interface
Syntax
elem = QUE_dequeue(queue);
Parameters
QUE_Handle queue;
/* queue object handle */
Return Value
Ptr
elem;
/* pointer to former first element */
Description
QUE_dequeue removes the element from the front of queue and returns
elem.
The return value, elem, is a pointer to the element at the front of the QUE.
Such elements have a structure defined similarly to that in the example
in the QUE Module topic. The first field in the structure must be of type
QUE_Elem and is used as an internal pointer.
Calling QUE_dequeue with an empty queue returns the queue itself.
However, QUE_dequeue is non-atomic. Therefore, the method
described for QUE_get of checking to see if a queue is empty and
returning the first element otherwise is non-atomic.
Note:
You should use QUE_get instead of QUE_dequeue if multiple threads
share a queue. QUE_get runs atomically and is never interrupted;
QUE_dequeue performs the same action but runs non-atomically. You
can use QUE_dequeue if you disable interrupts or use a
synchronization mechanism such as LCK or SEM to protect the queue.
An HWI or task that preempts QUE_dequeue and operates on the
same queue can corrupt the data structure.
QUE_dequeue is somewhat faster than QUE_get, but you should not
use it unless you know your QUE operation cannot be preempted by
another thread that operates on the same queue.
See Also
QUE_dequeue
Remove from front of queue (non-atomically)
