Advanced Search
Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Previous Book Contents Book Index Next

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

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 elementInstallation routineAdditional information
Slot-based VBL taskSlotVInstallThe chapter "Vertical Retrace Manager" in Inside Macintosh: Processes
System-based VBL taskVInstallThe 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 driveAddDriveThe chapter "File Manager" in Inside Macintosh: Files
EventPPostEvent and PostEventThe chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials
Volume control block*The chapter "File Manager" in Inside Macintosh: Files
Deferred taskDTInstallThe chapter "Deferred Task Manager" in Inside Macintosh: Processes
Slot interruptSIntInstallThe chapter "Slot Manager" in Inside Macintosh: Devices
Notification requestNMInstallThe chapter "Notification Manager" in Inside Macintosh: Processes
SleepSleepQInstallThe 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 elementRemoval routineAdditional information
Slot-based VBL taskSlotVRemoveThe chapter "Vertical Retrace Manager" in Inside Macintosh: Processes
System-based VBL taskVRemoveThe 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
EventWaitNextEventThe 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 interruptSIntRemoveThe chapter "Slot Manager" in Inside Macintosh: Devices
Notification requestNMRemoveThe chapter "Notification Manager" in Inside Macintosh: Processes
SleepSleepQRemoveThe 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.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996

Get information on Apple products.
Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Copyright © 2004 Apple Computer, Inc.
All rights reserved. | Terms of use | Privacy Notice