Inside Macintosh: Operating System Utilities /

Chapter 6 - Queue Utilities

Using the Queue Utilities

The Queue Utilities provide routines for directly adding elements to a queue and removing them from a queue. The Enqueue procedure lets you add elements to the end of a queue, and the Dequeue function lets you remove elements from a queue. You should manipulate an operating-system queue used by the Macintosh Operating System indirectly, by calling special-purpose routines. For example, to install a deferred task into a deferred task queue, your application should use the DTInstall function instead of the Enqueue procedure. However, if you create your own queues, you can use the Enqueue procedure and the Dequeue function to manipulate these queues directly. This section describes how to

• search for an element in an operating-system queue
• add an element to an operating-system queue
• remove an element from an operating-system queue

Searching for an Element in an Operating-System Queue

You can search an operating-system queue for a specific element or elements. For example, Listing 6-1 shows a simplified way to search a drive queue for all the drives connected to the computer. The application-defined function, MySearchDriveQueue, walks through the drive queue searches for all connected drives. If it finds any, it calls the application-defined function DoDisplayDriveInfo to display information about the connected drive.

Listing 6-1 Searching for drives in the drive queue

FUNCTION MySearchDriveQueue: Boolean;
VAR
   driveQHdr:     QHdrPtr;
   result:        Boolean;
BEGIN 
   result := FALSE;                          {assume no drivers in the queue}
   driveQHdr := GetDrvQHdr;                  {get the drive queue header}
   driveQPtr := DrvQElPtr(driveQHdr^.qHead);
   WHILE (driveQPtr <> NIL) DO               {while drive queue is not empty}
   BEGIN
      result := TRUE;                        {found a drive}
      DoDisplayDriveInfo(driveQPtr);         {display drive information}
                                             {go to next drive in the queue}
      driveQPtr := DrvQElPtr(driveQPtr^.qLink);
   END; {of while}
   MySearchDriveQueue := result;             {return result of search}
END;

Adding Elements to an Operating-System Queue

You should avoid direct manipulation of an operating-system queue used by the Macintosh Operating System. Your application should, when possible, use the installation routines in Table 6-2 to add new elements to an operating-system queue.

Table 6-2 Installation routines for operating-system queue elements

Queue element	Installation routine	Additional information
Slot-based VBL task	SlotVInstall	The chapter "Vertical Retrace Manager" in Inside Macintosh: Processes
System-based VBL task	VInstall	The chapter "Vertical Retrace Manager" in Inside Macintosh: Processes
Parameter block for an asynchronous routine awaiting execution	*	The chapter "File Manager" in Inside Macintosh: Files
Disk drive	AddDrive	The chapter "File Manager" in Inside Macintosh: Files
Event	PPostEvent and PostEvent	The chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials
Volume control block	*	The chapter "File Manager" in Inside Macintosh: Files
Deferred task	DTInstall	The chapter "Deferred Task Manager" in Inside Macintosh: Processes
Slot interrupt	SIntInstall	The chapter "Slot Manager" in Inside Macintosh: Devices
Notification request	NMInstall	The chapter "Notification Manager" in Inside Macintosh: Processes
Sleep	SleepQInstall	The chapter "Power Manager" in Inside Macintosh: Devices

IMPORTANT

It is not recommended that you directly add elements to an operating-system queue used by the Macintosh Operating System. If at all possible, your application should use the installation routines provided by the various managers.

If you have created a queue for your own use, you can use the Enqueue procedure to add a new element to your queue. For example, Listing 6-2 presents the application-defined procedure DoAddBankCustomer, which uses the Enqueue procedure for directly installing a customer into a bank-teller queue.

Listing 6-2 Using the Enqueue procedure to add a bank customer to a teller queue

PROCEDURE DoAddBankCustomer(myQueueHdrPtr: QHdrPtr,
                            Var bankCustomer: MyCustomerRecord);
BEGIN
   WITH bankCustomer^ DO               {get bank customer data}
   BEGIN
      qType := kTellerQType;           {queue type for the bank-teller queue}
      account := MyGetNextAccount;     {get account number}
      action := MyGetBankAction;       {get action to perform}
      amount := MyGetAmount;           {get the amount}
   END;
   Enqueue(QElemPtr(bankCustomer), myQueueHdrPtr);    {add customer to queue}
END;

Note that you are responsible for allocating memory for a queue element before you insert into a queue and for deallocating that memory when you remove the queue element.

Removing Elements From an Operating-System Queue

This section describes how your application can remove elements from an operating-system queue. Whenever possible, your application should use the removal routines listed in Table 6-3 to remove elements indirectly from an operating-system queue used by the Macintosh Operating System.

Table 6-3 Removal routines for operating-system elements

Queue element	Removal routine	Additional information
Slot-based VBL task	SlotVRemove	The chapter "Vertical Retrace Manager" in Inside Macintosh: Processes
System-based VBL task	VRemove	The chapter "Vertical Retrace Manager" in Inside Macintosh: Processes
Parameter block for an asynchronous routine awaiting execution	*	The chapter "File Manager" in Inside Macintosh: Files
Disk drive	*	The chapter "File Manager" in Inside Macintosh: Files
Event	WaitNextEvent	The chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials
Volume control block	*	The chapter "File Manager" in Inside Macintosh: Files
Deferred task	*	The chapter "Deferred Task Manager" in Inside Macintosh: Processes
Slot interrupt	SIntRemove	The chapter "Slot Manager" in Inside Macintosh: Devices
Notification request	NMRemove	The chapter "Notification Manager" in Inside Macintosh: Processes
Sleep	SleepQRemove	The chapter "Power Manager" in Inside Macintosh: Devices

IMPORTANT

It is not recommended that you directly remove queue elements from an operating-system queue used by the Macintosh Operating System. If at all possible, your application should use the removal routines provided by the various managers.

If you have created a queue for your own use, you can use the Dequeue function to remove elements from that queue.

Listing 6-3 shows the application-defined function DoRemoveBankCustomer, which uses the Dequeue procedure for directly removing the first customer from a bank-teller queue. The DoRemoveBankCustomer function returns TRUE if it removes the customer.

Listing 6-3 Using Dequeue to remove the first customer in the bank-teller queue

FUNCTION DoRemoveBankCustomer (VAR myQueueHdr: QHdr): BOOLEAN;
VAR
   bankCustomerPtr: MyCustomerRecordPtr;
   customerRemoved: Boolean;

BEGIN
   customerRemoved := FALSE;
   bankCustomerPtr := MyCustomerRecordPtr(myQueueHdr.qHead);
   IF bankCustomerPtr <> NIL THEN      {Check for non-empty queue}
   BEGIN
      Dequeue(QElemPtr(bankCustomerPtr),&myQueueHdr) {remove customer}
      customerRemoved := TRUE;
   END; {of queue not empty}
   DoRemoveCustomer := customerRemoved;
END;

---

* No comparative installation routine available.

---