Inside Macintosh: Operating System Utilities /

Chapter 6 - Queue Utilities / Queue Utilities Reference

Routines /

Dequeue

You can use the Dequeue function to remove a queue element directly from an operating-system queue or from a queue that you have created.

FUNCTION Dequeue (qElement: QElemPtr; qHeader: QHdrPtr): OSErr;

qElement

A pointer to a queue element to remove from a queue.

qHeader

A pointer to a queue header.

DESCRIPTION

The Dequeue function attempts to find the queue element specified by the qElement parameter in the queue specified by the qHeader parameter. If Dequeue finds the element, it removes the element from the queue, adjusts the other elements in the queue accordingly, and returns noErr. Otherwise, it returns qErr, indicating that it could not find the element in the queue. The Dequeue function does not deallocate the memory occupied by the queue element.

SPECIAL CONSIDERATIONS

The Dequeue function disables interrupts as it searches through the queue for the element to be removed. The time during which interrupts are disabled depends on the length of the queue and the position of the entry in the queue. The Dequeue function can be called at interrupt time. Whenever possible, use the removal routines listed in Table 6-3 on page 6-12 instead the Dequeue function.

ASSEMBLY-LANGUAGE INFORMATION

The registers on entry and exit for the Dequeue function are

Registers on entry
A0	Pointer to the queue element to be removed
A1	Pointer to the queue header

Registers on exit
A1	Pointer to the queue header
D0	Result code

RESULT CODES

noErr	0	No error
qErr	-1	Entry is not in specified queue

SEE ALSO

For a description the QElem record, see page 6-14; for a description of the QHdr record, see page 6-13.