MacApp Low Priority
Volume Number: 11
Issue Number: 2
Column Tag: Improving The Framework
Using Low Priority Events in MacApp 
Fixing a minor bug gets your priorities straight
By Harry Haddon, Franklin & Marshall College
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Just like most standard Macintosh programs, MacApp has a main event loop, but as
with many things, MacApp handles the gory details of the event loop for you while still
giving you the flexibility to expand or improve upon it as needed. The focus of
MacApp’s event loop is MacApp’s event list which usually contains commands but can
also contain more generalized events. Commands and events posted to this list can have
different priorities to change the order in which they are processed. The only problem
is that MacApp 3.0 and 3.1 never actually process your low priority events.
This article gives a quick overview of the MacApp event list, explains why you
might want to use an event with a low priority, and tells you how to fix
MacApp-without modifying the MacApp source-so low priority events are properly
processed.
Inside the Event List
The MacApp event list is of type TEventList and is a data member, named fEventList, of
TApplication. TEventList contains objects of type TEvent and objects descended from
TEvent including objects of type TCommand. Since TCommand is a descendent of
TEvent, I will use the word “events” in this article to refer to both events and
commands.
When you call PostAnEvent() or PostCommand(), the TEventHandler
implementations of these two methods pass the event to the next event handler in the
event handler chain until TApplication::PostAnEvent() gets the event and inserts it in
fEventList sorted by priority. TApplication’s main event loop method retrieves events
from fEventList and handles the events by calling their Process() method. The highest
priority events, those with their fPriority field set to kPriorityHighest, are retrieved
before the lower priority ones. The priorities defined by MacApp are:
// Low priority commands are considered last
const short kPriorityLowest = 127;
const short kPriorityLow = kPriorityLowest - 32;
// Normal priority: command default priority
const short kPriorityNormal = 64;
const short kPriorityHigh = kPriorityNormal - 32;
//High priority commands take precedence
const short kPriorityHighest = 0;
If you wish you can use priority values which are between these constants. The
default priority for events is kPriorityNormal.
Events of equal priority in fEventList are not necessarily processed on a
First-In, First-Out basis. MacApp uses a binary search when inserting events in
fEventList and inserts the event at the first event it finds of equal priority. If you post
an event and there are already two or more events of equal priority in the list, their
order in the list is indeterminate and hence their order of processing is indeterminate.
This is not normally a problem since the typical MacApp application does not have that
many equal priority events in the list at one time, but it is something to consider if
you’re posting multiple commands to the list at the same time and the order of
processing is important.
One command you’ll always find in fEventList is the TEventRetrieverCommand
that MacApp uses to fetch toolbox events from the toolbox’s Event Manager. The
initialization method IApplication() creates this command with a priority of
kPriorityLow and posts it to fEventList. The command stays in the list as long as the
application is running, and its sole job is to check for toolbox events. Since
TEventRetrieverCommand has a lower priority than normal, MacApp does not process
it until after it processes the events in the list that have a normal priority. Thus
MacApp won’t fetch any more events from the toolbox queue until after it has processed
all of the normal priority events and commands in fEventList.
TEventRetrieverCommand::DoIt() checks for toolbox events by calling
gApplication->PollToolboxEvent() which calls the toolbox trap WaitNextEvent(). If a
toolbox event is available, it is encapsulated in a TToolboxEvent and processed by
MacApp. If no toolbox event is available and TApplication.fAllowApplicationToSleep is
true, MacApp figures out the various sleep parameters such as the sleep time and calls
WaitNextEvent() to wait for the next toolbox event.
This all works great unless you try to post an event with a priority of
kPriorityLow or lower. Then you will find that the TEventRetrieverCommand in
fEventList acts as a road block for low priority events. Because it was posted first, it
is processed before all events of the same priority (kPriorityLow). If no toolbox
events are available from the Macintosh event queue, the TEventRetrieverCommand
puts the application to sleep, preventing the processing of any low priority events
remaining in fEventList. If a toolbox event is available, MacApp processes it, as it
should, leaving no opportunity for the processing of low priority events.
Why Use Low Priority Events?
I ran into the bug with low priority events when I was developing a client application
that fetches data from a server application. I used a descendent of TClientCommand,
MacApp’s class for sending an Apple event and processing its reply, to fetch the data
from the server. The server collects new data at the rate of 10 samples per second and
the client needs to be updated at least several times a second so as soon as a reply is
received, the client posts another TClientCommand to fetch the next chunk of data.
My TClientCommand needed to be a lower priority than toolbox events so that the
view that was changed by the TClientCommand would be updated via an update event
before the next TClientCommand was processed. I also wanted the application to
process toolbox events before it did the TClientCommand so that the application would
be responsive to user actions such as mouse clicks. Experimentation with the
TClientCommand’s priority set to kPriorityNormal on a slower Macintosh confirmed
that being able to set its priority lower was a worthy goal.
You may have a similar situation where a low priority command would fit the
bill. Remember that low priority commands really aren’t background or idle
commands: they do not execute until after higher priority events have executed, but
once they begin execution they can hog CPU cycles as much as any other event. If they
take too much time to execute they can slow down the processing of user actions and
create a less than enjoyable experience for your user. Design your commands
accordingly.
Fixing the Low Priority Event Bug
I came up with a fairly simple fix that I have used with MacApp 3.0.1. This fix will
probably also work with 3.1, since it appears that the relevant sections of code have
not changed from 3.0 to 3.1. It is not a perfect fix in that events with the very lowest
priority, kPriorityLowest, are still not processed, but this is not really a problem
since you can use a priority of kPriorityLowest-1 for your lowest priority, and it
will work fine.
The original TEventRetrieverCommand, which is installed by IApplication, is left
in fEventList but its priority is changed to kPriorityLowest. This still allows the
application to sleep-a Good Thing in the Macintosh world of cooperative
multi-tasking-but it does not go to sleep until after all other commands are given a
chance to execute. I changed the priority of TEventRetrieverCommand in
IMyApplication() after calling IApplication():
TEventRetrieverCommand *originalEventRetriever;
originalEventRetriever =
(TEventRetrieverCommand *) fEventList->At(1);
originalEventRetriever->fPriority = kPriorityLowest;
if (qDebug && !originalEventRetriever->IsMemberClass(
GetClassIDFromName("TEventRetrieverCommand")))
ProgramBreak("First command in fEventList is not
a TEventRetrieverCommand!");
This code doesn’t look for the TEventRetrieverCommand on the event list but just
assumes that it's the first command on the list. The debug check will warn me if this
isn’t true in future versions of MacApp. (Hopefully Apple will fix this in MacApp 3.5
and we won’t need this fix at all anymore.)
To keep processing toolbox events at kPriorityLow, I declared a new command
that is a descendant of TEventRetrieverCommand. This command checks for toolbox
events but never sleeps. It is posted at kPriorityLow to replace the original
TEventRetrieverCommand that was demoted to kPriorityLowest.
class TNoSleepEventRetrieverCommand :
public TEventRetrieverCommand {
public:
TNoSleepEventRetrieverCommand();
// Empty constructor to satisfy compiler.
virtual pascal void INoSleepEventRetrieverCommand(
CommandNumber itsCommandNumber);
// Initialize the EventCommand procedurally.
virtual pascal Boolean IsReadyToExecute();
// override
// Return true when event available
virtual pascal void DoIt();
// Retrieve and process an event without sleeping
};
I put the declaration for TNoSleepEventRetrieverCommand in the header file that
contains the declaration for TMyApplication.
I put the definitions for its methods in the .cp file that contains the methods of
TMyApplication. The initialization method INoSleepEventRetrieverCommand() just
calls IEventRetrieverCommand() and then sets the command's priority:
#pragma segment ASelCommand
pascal void
TNoSleepEventRetrieverCommand::INoSleepEventRetrieverCommand(
CommandNumber itsCommandNumber)
{
this->IEventRetrieverCommand(itsCommandNumber);
// Let more important stuff happen first
fPriority = kPriorityLow;
}
Its IsReadyToExecute method returns true whenever a toolbox event is available:
#pragma segment ARes
pascal Boolean TNoSleepEventRetrieverCommand::IsReadyToExecute()
{
EventRecord theEvent;
return EventAvail(gApplication->fMainEventMask, theEvent);
}
When IsReadyToExecute() returns true, MacApp calls the command’s DoIt()
method. The DoIt() for TNoSleepEventRetrieverCommand is just like DoIt() for
TEventRetrieverCommand except it calls PollToolboxEvent() with the parameter
allowApplicationToSleep set to false so the application doesn’t go to sleep on us:
#pragma segment ASelCommand
pascal void TNoSleepEventRetrieverCommand::DoIt()
{
gApplication->PollToolboxEvent(FALSE);
// FALSE = never sleep
}
The TNoSleepEventRetrieverCommand is created and posted in TMyApplication
after the priority of the original TEventRetrieverCommand is changed:
TNoSleepEventRetrieverCommand *aEventCommand =
new TNoSleepEventRetrieverCommand;
aEventCommand->INoSleepEventRetrieverCommand(cNoCommand);
this->PostAnEvent(aEventCommand);
That’s it. With these fixes in place you can post a command with a priority of
kPriorityLow or lower, and MacApp will process it as it should.