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

Mellel 3.5.5 - The word processor for sc...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
Bookends 12.8.3 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
Carbon Copy Cloner 4.1.18 - Easy-to-use...
Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more
Hopper Disassembler 4.2.14- - Binary dis...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
BetterTouchTool 2.291 - Customize Multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Sound Studio 4.8.11 - Robust audio recor...
Sound Studio lets you easily record and professionally edit audio on your Mac. Easily rip vinyls and digitize cassette tapes, or record lectures and voice memos. Prepare for live shows with live... Read more
Sound Studio 4.8.11 - Robust audio recor...
Sound Studio lets you easily record and professionally edit audio on your Mac. Easily rip vinyls and digitize cassette tapes, or record lectures and voice memos. Prepare for live shows with live... Read more
BetterTouchTool 2.291 - Customize Multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Carbon Copy Cloner 4.1.18 - Easy-to-use...
Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more
Hopper Disassembler 4.2.14- - Binary dis...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more

The best 2v2 card combos in Clash Royale
2v2 is making it's grand return toClash Royalequite soon. 2v2 has quickly become one of the game's most popular gameplay modes, though they still have yet to make it a permanent fixture in the game. 2v2 is exciting and adds some new flavor to... | Read more »
The best games we played this week - Aug...
Another busy week has come to a close. We played a lot of excellent games this week and now it's time to look back and reflect on some our favorites. Here are our picks for the week of August 18. [Read more] | Read more »
War Wings beginner's guide - how to...
War Wings is the newest project from well-established game maker Miniclip. It's a World War II aerial dogfighting game with loads of different airplane models to unlock and battle. The game offers plenty of single player and multiplayer action. We... | Read more »
How to win every 2v2 battle in Clash Roy...
2v2 is coming back to Clash Royale in a big way. Although it's only been available for temporary periods of time, 2v2 has seen a hugely positive fan response, with players clamoring for more team-based gameplay. Soon we'll get yet another taste of... | Read more »
Roll to Win with Game of Dice’s new upda...
Joycity’s hit Game of Dice gets a big new update this week, introducing new maps, mechanics, and even costumes. The update sets players loose on an exciting new map, The Cursed Tower, that allows folks to use special Runes mid-match. If you feel... | Read more »
Bottom of the 9th (Games)
Bottom of the 9th 1.0.1 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: Play the most exciting moment of baseball in this fast-paced dice and card game! | Read more »
The best apps for viewing the solar ecli...
If you somehow missed the news, many parts of the United States will be witness to a total solar eclipse on August 21 for the first time in over 90 years. It'll be possible to see the eclipse in at least some capacity throughout the continental U... | Read more »
The 5 best mobile survival games
Games like ARK: Survival Evolved and Conan Exiles have taken the world of gaming by storm. The market is now flooded with hardcore survival games that send players off into the game's world with nothing but maybe the clothes on their back. Never... | Read more »
Portal Walk (Games)
Portal Walk 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Portal Walk is adventure and relaxing platform game about Eugene. Eugene stuck between worlds and trying to find way back home.... | Read more »
Technobabylon (Games)
Technobabylon 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: City of Newton, 2087. Genetic engineering is the norm, the addictive Trance has replaced almost any need for human interaction,... | Read more »

Price Scanner via MacPrices.net

15-inch 2.2GHz Retina MacBook Pro, Apple refu...
Apple has Certified Refurbished 2015 15″ 2.2GHz Retina MacBook Pros available for $1699. That’s $300 off MSRP, and it’s the lowest price available for a 15″ MacBook Pro. An Apple one-year warranty is... Read more
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
Apple refurbished iPad Pros available startin...
Apple has Certified Refurbished 2016 12″ WiFi iPad Pros available starting at $589. An Apple one-year warranty is included with each model, and shipping is free: – 32GB 12″ iPad Pro WiFi: $589... Read more
Weekend sale: 13-inch MacBook Pros for up to...
Amazon has new 2017 13″ MacBook Pros on sale today for up to $200 off MSRP, each including free shipping: – 13″ 3.1GHz/256GB Space Gray MacBook Pro (MPXV2LL/A): $1599.99 $200 off MSRP – 13″ 3.1GHz/... Read more
Back To School With The Edge Desk All-in-one...
Back to school is just around the corner, and the ergonomically correct Edge Desk all-in-one portable kneeling desk is ideal for students living in dorms and small apartments, Edge Desk features:... Read more
Norton Core Secure Wi-Fi Router Now Available...
First introduced at the 2017 Consumer Electronics Show (CES), Norton Core, a secure, high-performance Wi-Fi router, fundamentally changed the concept of Wi-Fi routers by making security the primary... Read more
ViewSonic Adds New 27-inch 4K UHD Monitor to...
ViewSonic Corp. has introduced the VP2785-4K, a 27-inch 4K UHD (3840×2160) monitor that delivers precise and consistent color representation and performance to ensure incredible image quality. Built... Read more
Apple now offering Certified Refurbished 2017...
Apple is now offering Certified Refurbished 2017 27″ iMacs for up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: – 27″ 3.... Read more
13-inch 2.3GHz MacBook Pros on sale for $100...
Amazon has the new 2017 13″ 2.3GHz MacBook Pros on sale today for $100 off MSRP, each including free shipping: – 13″ 2.3GHz/128GB Space Gray MacBook Pro (MPXQ2LL/A): $1199.99 $100 off MSRP – 13″ 2.... Read more
Clearance 2016 13-inch MacBook Airs available...
B&H Photo has clearance 2016 13″ MacBook Airs available for up to $200 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: – 13″ 1.6GHz/128GB MacBook Air (MMGF2LL... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple I...
Job Summary The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant - Apple Inc. (U...
…about helping others on a team while also delighting customers? As an Apple Solutions Consultant (ASC), you will discover customers needs and help connect them Read more
Development Operations and Site Reliability E...
Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
Map Quality Analyst Lead, *Apple* Maps Eval...
…a team of subject matter experts measuring the quality of a range of Apple Maps algorithms, such as Map search, recommendations, and routing. Our group works with Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.