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

VOX 2.8.6 - Music player that supports m...
VOX just sounds better! The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features and support for all audio formats you should ever need.... Read more
MacUpdate Desktop 6.1.3 - Search and ins...
MacUpdate Desktop 6 brings seamless 1-click app installs and version updates to your Mac. With a free MacUpdate account and MacUpdate Desktop 6, Mac users can now install almost any Mac app on... Read more
ExpanDrive 5.4.1 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Espionage 3.6.6 - Simple, state-of-the-a...
Espionage offers state-of-the-art encryption and plausible deniability for your confidential data. Sometimes, encrypting your data isn't enough to protect it. That's why Espionage 3 goes beyond data... Read more
Pinegrow Web Designer 2.94 - Mockup and...
Pinegrow Web Designer is desktop app that lets you mockup and design webpages faster with multi-page editing, CSS and LESS styling, and smart components for Bootstrap, Foundation, Angular JS, and... Read more
1Password 6.3.3 - Powerful password mana...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
Sublime Text 3126 - Sophisticated text e...
Sublime Text is a sophisticated text editor for code, markup, and prose. You'll love the slick user interface, extraordinary features, and amazing performance. Features Goto Anything. Use Goto... Read more
ForkLift 3.0 Beta 2 - Powerful file mana...
ForkLift is a powerful file manager and ferociously fast FTP client clothed in a clean and versatile UI that offers the combination of absolute simplicity and raw power expected from a well-executed... Read more
OmniFocus 2.7.1 - GTD task manager with...
OmniFocus helps you manage your tasks the way that you want, freeing you to focus your attention on the things that matter to you most. Capturing tasks and ideas is always a keyboard shortcut away in... Read more
CleanApp 5.1.1 - Application deinstaller...
CleanApp is an application deinstaller and archiver.... Your hard drive gets fuller day by day, but do you know why? CleanApp 5 provides you with insights how to reclaim disk space. There are... Read more

Leaf for Twitter (Social Networking)
Leaf for Twitter 1.0.1 Device: iOS iPhone Category: Social Networking Price: $4.99, Version: 1.0.1 (iTunes) Description: | Read more »
Banner Saga 2 (Games)
Banner Saga 2 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: The epic award winning story-based role-playing game continues its emotional journey across a breaking world. Lead your Viking... | Read more »
Concrete Jungle (Games)
Concrete Jungle 1.16 Device: iOS Universal Category: Games Price: $4.99, Version: 1.16 (iTunes) Description: A follow up to the puzzle hit 'MegaCity'! Concrete Jungle is a new take on the city building genre that swaps micro-... | Read more »
5 great apps for the budget traveller
Travelling abroad, or even within your home country, has never been easier thanks to our handy smartphone companions. There are hundreds of apps on the market that promise to make your world journeys hassle-free, but we've selected five of the... | Read more »
Zip—Zap (Games)
Zip—Zap 1.01 Device: iOS Universal Category: Games Price: $1.99, Version: 1.01 (iTunes) Description: Touch to contract.Release to let go.Bring the clumsy mechanical beings home. · · · over 100 levelsno adsno in-app-purchases Zip—... | Read more »
Paperback: The Game (Games)
Paperback: The Game 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: You are an author trying to finish kitschy paperback novels. Complete Westerns, Science Fiction, Romance or even a Crime... | Read more »
How to Rule With a Firm Hand in My Majes...
My Majesty is a kingdom management sim not unlike August’s magisterial hit, Reigns. It’s essentially a reskin of developer Tigrido’s previous management sim, Dictator. As supreme ruler of the land, you must consult with a number of subjects to... | Read more »
Our 5 Favorite iMessage Sticker Packs
At long last, iMessage joins the ranks of messaging apps the likes of LINE and Whatsapp, adding an impressive collection of stickers. They’re a great way to add a little something extra to your daily conversations. [Read more] | Read more »
How to get past Vulture Island's tr...
Vulture Island is a colorful and quirky mish-mash of platforming and puzzles. It’s creative and fresh, but sometimes the game can throw a curveball at you, leaving you stuck as to how you should progress. These tips will help you explore smoothly... | Read more »
The new Clash of Kings is just for Weste...
If you’ve played the original Clash of Kings, you’ll probably recognise the city building, alliance forging and strategic battles in Clash of Kings: The West. What sets this version apart is that it’s tailor made for a Western audience and the... | Read more »

Price Scanner via MacPrices.net

Apple refurbished Mac minis available startin...
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 available for $928...
Overstock has the 13″ 2.5GHz MacBook Pro available for $927.99 including free shipping. Their price is $171 off MSRP. Read more
Buying McLaren Would Give Apple Instant Car C...
Apple “iCar” rumors have waxed and waned over the years, piquing interest and speculation as to whether Apple is seriously interested in getting into the automotobile business, either in a joint... Read more
Aetna to Transform Members’ Consumer Health E...
Health care benefits company Aetna, which has an estimated 46.3 million clients, today announced a new initiative to revolutionize members consumer health experience by combining the power of iOS... Read more
USB-IF Announces USB Audio Device Class 3.0 S...
USB Implementers Forum (USB-IF), the support organization for the advancement and adoption of USB technology, today announced the USB Audio Device Class 3.0 specification to establish USB Audio over... Read more
Clearance 12-inch 1.2GHz Retina MacBooks, App...
Apple has Certified Refurbished 2015 12″ 1.2GHz Retina MacBooks available for $1189, or $410 off original MSRP. Apple will include a standard one-year warranty with each MacBook, and shipping is free... Read more
Logitech SmartDock and Skype For Business Com...
Logitech has announced Logitech SmartDock, an AV meeting room solution designed in collaboration with Microsoft. Logitech SmartDock works with Skype for Business and qualified devices, including... Read more
27-inch iMacs on sale for up to $220 off MSRP
B&H Photo has 27″ Apple iMacs on sale for up to $200 off MSRP including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2099 $200 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $1899.99 $... Read more
Apple Macs and iPads available for up to $300...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
Save up to $600 with Apple refurbished Mac Pr...
Apple has Certified Refurbished Mac Pros available for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The following... Read more

Jobs Board

*Apple* Retail - Multiple Positions- Chicago...
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* Retail - Multiple Positions- Raleigh...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
User Support Specialist *Apple* Product Spe...
…Description:Ciber, Inc. is seeking a User Support Specialist - Apple Product Support in Nashville, TN!Responsibilities:Support, implementation, and upgrade of Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
US- *Apple* Store Leader Program - Apple (Un...
…Summary Learn and grow as you explore the art of leadership at the Apple Store. You'll master our retail business inside and out through training, hands-on Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.