TweetFollow Us on Twitter

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 or source 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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Is there cross-platform play in slither....
So you've sunken plenty of hours into crawling around in slither.io on your iPhone or iPad. You've got your stories of tragedy and triumph, the times you coiled four snakes at one time balanced out by the others when you had a length of more than... | Read more »
Rodeo Stampede guide to running a better...
In Rodeo Stampede, honing your skills so you can jump from animal to animal and outrun the herd as long as possible is only half the fun. Once you've tamed a few animals, you can bring them home with you. [Read more] | Read more »
VoxSyn (Music)
VoxSyn 1.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0 (iTunes) Description: VoxSyn turns your voice into the most flexible vocal sound generator ever. Instantly following even subtle modulations of pitch and... | Read more »
Catch Battleplans on Google Play from Ju...
Real-time strategy title Battleplans is due for release on Google Play on June 30th, following its release for iOS systems last month. With its simple interface and pretty graphics, the crowd-pleaser brings a formerly overlooked genre out for the... | Read more »
iDoyle: The interactive Adventures of Sh...
iDoyle: The interactive Adventures of Sherlock Holmes - A Scandal in Bohemia 1.0 Device: iOS Universal Category: Books Price: $1.99, Version: 1.0 (iTunes) Description: Special Release Price $1.99 (Normally $3.99) | Read more »
Five popular free apps to help you slim...
Thanks to retail and advertising, we're used to thinking one season ahead. Here we are just a week into the summer and we're conditioned to start thinking about the fall. [Read more] | Read more »
How to ride longer and tame more animals...
It's hard to accurately describe Rodeo Stampede to people who haven't seen it yet. It's like if someone took Crossy Roadand Disco Zoo and put them in a blender, yet with a unique game mechanic that's still simple and fun for anyone. [Read more] | Read more »
Teeny Titans - A Teen Titans Go! Figure...
Teeny Titans - A Teen Titans Go! Figure Battling Game 1.0.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.0 (iTunes) Description: Teeny Titans, GO! Join Robin for a figure battling RPG of epic proportions! TEENY... | Read more »
NinjAwesome: Tips and tricks to be a mor...
Sorry about that headline, but I'm going to go ahead and assume that GameResort would not have named its game NinjAwesome without expecting some of that. It is, in fact, pretty awesome the way it combines an endless runner and old school arcade... | Read more »
Into Mirror (Games)
Into Mirror 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: "Is all that we see or seem, but a dream within a dream?"- Edgar Allan Poe New game by Lemon Jam Studio, the team behind Pursuit... | Read more »

Price Scanner via MacPrices.net

13-inch Retina MacBook Pros on sale for up to...
B&H Photo has 13″ Retina MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1179 $120 off MSRP - 13″ 2.7GHz/... Read more
Apple refurbished Mac minis available for up...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
13-inch 2.5GHz MacBook Pro on sale for $999,...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Apple refurbished iMacs available for up to $...
Apple has Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: - 21″ 3.... Read more
15-inch Retina MacBook Pros on sale for $200-...
B&H Photo has 15″ Retina MacBook Pros on sale for up to $210 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799.99 $200 off MSRP - 15″ 2.5GHz... Read more
Mac minis on sale for up to $100 off MSRP
B&H Photo has Mac minis on sale for up to $100 off MSRP including free shipping plus NY sales tax only: - 1.4GHz Mac mini: $449 $50 off MSRP - 2.6GHz Mac mini: $649 $50 off MSRP - 2.8GHz Mac mini... Read more
Clearance 2015 13-inch MacBook Airs available...
B&H Photo has clearance 2015 13″ MacBook Airs available for $300 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/4GB/128GB MacBook Air (MJVE2LL/A): $799.... Read more
Apple refurbished Mac minis available for up...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
ABBYY TextGrabber: 1,000,000 Installs in 5 Da...
ABBYY, an international OCR technologies provider, has announced that their image-to-text application TextGrabber, got installed 1,000,000 times in just five days while being featured by the App... Read more
New SkinIt Waterproof Case For iPhone 6
With its impact and waterproof design, the Skinit Waterproof case provides security and protection to guarantee your phone will get you through even the most demanding outdoor conditions. The impact-... Read more

Jobs Board

*Apple* Retail - Multiple Positions, Towson...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
Music Marketing Lead, iTunes & *Apple*...
…Music Marketing Lead is responsible for developing robust marketing campaigns and programs for Apple Music and iTunes across the whole of Apple ecosystem. This Read more
*Apple* Valley Medical Clinic is Hiring - AP...
Apple Valley Medical Clinic is Hiring! Apple Valley Medical Clinic is an independently owned practice operating a Family Medicine Clinic, a 24/7 Urgent Care, Read more
*Apple* New Products Testers Needed - Apple...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.