TweetFollow Us on Twitter

Threaded Apple Events

Threading Apple Events

Or: How I Learned to Stop Worrying and Love to Bomb

By Grant Neufeld, InfoDesign Corporation

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

As Jon Wiederspan points out elsewhere in this issue, threading is becoming a serious problem for webmasters intent on getting speed out of their servers. In C the problem is compounded because the AppleEvent Manager does not handle multiple simultaneous events (and Apple events are used to communicate with CGI applications). Grant Neufeld has developed a solution to this problem and distributes a CGI framework that implements it for you. In this article, he shows us how it's done.

On the Thread Manager, see also:

For Frontier as a possible solution to threading difficulties, see MacTech Magazine 12.1 (January 1966) 63-65; see also the technologies discussed by Jon in our MacWorld Expo report. On writing your CGI in C, see MacTech Magazine 11.9 (September 1995) 33-42.

The Problem of Reentrancy

As I recently discovered, trying to combine Apple events with the Thread Manager is an awkward and mind-altering experience. There are some fundamental - and obscure - requirements that are easy to miss (or so I'd like everyone to believe, so that I don't have to be so embarrassed by my own oversight).

The fundamental problem is that AEProcessAppleEvent is non-reentrant. So, if you call it, you can't call it again until the event finishes processing. I didn't know this when I originally designed the threading for my CGI framework, so I happily set about an implementation whereby I could call AEProcessAppleEvent multiple times before finishing the first call - all through the glory of the Thread Manager. My incorrect code looked like:

/* warning: bad code! Don't try this at home! */
/* Called from main event loop when a high level event arrived. */
void doHighLevelEvent ( EventRecord *theEvent )
{
 OSErr     theErr;
 ThreadID  theThread;
 
 if ( gHasThreadMgr ) {
// MyNewThreadFromPool is just a custom method to simplify
// using threads from a pool.
// Remember: this particular example of Apple event threading
// is wrong - don't do it this way!
 theErr = MyNewThreadFromPool ( doAEThread, theEvent,
 (void**)nil, &theThread );
 }
 if ( !gHasThreadMgr || (theErr != noErr) ) {
// If threading isn't available, or the attempt to thread failed,
// process the Apple event without threading.
 theErr = AEProcessAppleEvent ( theEvent );
 }
}

/* The thread entry function that was used to process the Apple event. */
pascal void * doAEThread ( void *theEvent )
{
 OSErr     theErr;
 ThreadID  currentThread;
 
 theErr = AEProcessAppleEvent ( (EventRecord *)theEvent );
 
 GetCurrentThread ( &currentThread );
 DisposeThread    ( currentThread, (void *)theErr, true );
 
 return (void *)theErr;
}

The amazing thing is that nobody - including me - caught the error until Wayne K. Walrath took a look at the code (in the eleventh release) and noticed my mistake. By then, programs were already shipping and in commercial use - including my own Random URL CGI.

So, why didn't anyone notice the code crashing? The code we all had in our threads happened to be fast enough to finish before new Apple events came in. This doesn't mean it would never crash; given a situation where two Apple events came in almost simultaneously, the code would certainly flop.

Thankfully, I had the prescience to include a suitable disclaimer and label the code "beta" and "subject to errors" to cover my legal posterior. However, my public esteem was in jeopardy! Worse still, I couldn't touch the code for a few days after receiving the bug report because of job obligations. Actually, that was a good thing because the time spent thinking about the code gave me a good basis to start from when I did actually get down to work.

Moral: Think before you code. (Carefully reading the documentation isn't a bad idea either!)

Suspending Apple Events

My original code attempted to thread every Apple event. This is not the case with the corrected code. A new thread should only be initiated within the context of an AEProcessAppleEvent call if the Apple event has been successfully suspended. Suspension of Apple events involves calls to the functions AESuspendTheCurrentEvent and AEResumeTheCurrentEvent.

If the Apple event does not suspend, you can't make any further calls to AEProcessAppleEvent, so you must not create a sub-thread unless you implement a mechanism to prevent calls to AEProcessAppleEvent until the current Apple event finishes. If you want to be creative, you can write your own Apple event dispatcher to allow reentrancy, thereby making it easier to deal with threads. People might call you crazy, but you can do it.

Which brings us to the obligatory complaint about lack of sufficient (and clear) documentation (which is part of the reason I'm writing this). Inside Macintosh: Interapplication Communication doesn't sufficiently cover the use of the necessary calls and provides no sample code for suspending Apple events (see IM:IAC 4.85-88). Hopefully, this article helps fill that gap.

The CGI Apple event is the only one I'm concerned about threading for my framework, so I didn't bother with any of the other events. I handle the Apple event arrival in the normal way with a handler installed to be called by AEProcessAppleEvent:

/* Apple event Handler for the CGI WWW sdoc event */
pascal OSErr
CGIAESearchDoc ( AppleEvent *theAppleEvent,
 AppleEvent *theReply, long Reference )
{
 OSErr     theErr;
 CGIHdl    theCGIHdl;
 ThreadID  theThread;
 
// Allocate the CGIHdl data structure - zeroing out its contents.
 theCGIHdl = (CGIHdl)
 MyNewHandleClear ( sizeof(CGIrecord), &theErr );
 if ( theCGIHdl == nil ) {
 return theErr;
 }
 
// Store references to the apple event and reply records.
 (*theCGIHdl)->appleEvent = *theAppleEvent;
 (*theCGIHdl)->replyEvent = *theReply;
 
 if ( gHasThreadMgr ) {
// It is necessary to suspend the Apple event in order to thread its processing
// because of some real weirdness with AEProcessAppleEvent not being
// "reentrant." This means you can't be processing multiple Apple events at
// the same time, so they have to be ‘suspended' if you want to deal with more
// than one (I.E., multi-threaded processing).
 theErr = AESuspendTheCurrentEvent ( theAppleEvent );
 if ( theErr == noErr) {
 (*theCGIHdl)->suspended = true;
// Apple event has been suspended, so we can spawn a thread for processing.
 theErr = MyNewThreadFromPool (
 CGIAESearchDocProcessThread, theCGIHdl,
 (void**)nil, &theThread );
 }
 }
 
 if ( !gHasThreadMgr || (theErr != noErr) ) {
// If threading isn't available, or the attempt to thread failed, or the attempt to
// suspend the Apple event failed, process the Apple event without threading.
 theErr = cgiAESearchDocProcess ( theCGIHdl );
 } else {
// We suspended the Apple event, and spawned the thread, now let's start it.
 YieldToThread ( theThread );
 }
 
 return theErr;
}

The support for threading begins in the CGIAESearchDoc function. First, I confirm the presence of the Thread Manager. If it is available, I attempt to suspend the Apple event so that it will be safe to process subsequent Apple events before finishing the current one. If the suspension is successful, I call my thread function for the event, which in turn calls the function that does the actual work of handling the event request.

/* Entry point for CGI handler thread. threadParam must not be nil. */
pascal void *
CGIAESearchDocProcessThread ( void *threadParam )
{
 OSErr     theErr;
 CGIHdl    theCGIHdl;
 ThreadID  currentThread;
 
// The threadParam is used to pass the CGIHdl.
 theCGIHdl = (CGIHdl)threadParam;
 
 theErr = cgiAESearchDocProcess ( theCGIHdl );
 
// Find the ID of current thread and use DisposeThread to dispose of it so that 
// my custom thread termination procedure will be used to recover this thread's
// allocation for the thread pool.
 GetCurrentThread ( &currentThread );
 DisposeThread ( currentThread, (void *)theErr, true );
 
// This line below is actually irrelevant, since the DisposeThread call above
// will result in the immediate termination of this thread.
// I keep it in because a return result is needed for the compiler not to issue a
// warning (and I have the "treat all warnings as errors" flag set in my
// compiler, like every programmer should).
 return (void *)theErr;
}

The basic flow of my CGI Apple event handling (if we ignore the threading) starts with CGIAESearchDoc which leads to cgiAESearchDocProcess (which calls CGIAEResumeComplete if the Apple event is suspended), finishing with cgiAEComplete. This structure allows the necessary threading and Apple event "wrapper" functions to be put around the cgiAESearchDocProcess. If the Apple event is successfully suspended, an attempt is made to create the thread, which then carries the remainder of the processing. If either the suspend or thread fails, processing will still occur - just without threading.

Resuming the Apple event

cgiAESearchDocProcess checks the suspension of the Apple event to determine how it should call the completion function. If the Apple event was suspended, it must be resumed using AEResumeTheCurrentEvent before cgiAEComplete can be called.

/* Process the CGI WWW sdoc Apple event.
    theCGIHdl must be valid (non-nil) and unlocked. */
static OSErr
cgiAESearchDocProcess ( CGIHdl theCGIHdl )
{
 OSErr       theErr;
 AppleEvent  theAppleEvent;
 
// Copy the AppleEvent record pointer into a local variable for faster access.
 theAppleEvent = (*theCGIHdl)->appleEvent;
 
// The following section (not shown in this listing) is where the parameters are
// pulled from the CGI Apple event and allocated in the CGI Handle.
// That is followed by a call to the application specific CGI handler function.
 
 if ( (*theCGIHdl)->suspended ) {
// We're in a suspended Apple event, so we'll need to resume the
// Apple event to have it complete and return the reply properly.
 theErr = AEResumeTheCurrentEvent (
 &theAppleEvent, &((*theCGIHdl)->replyEvent),
 vCGIAEResumeCompleteUPP, (long)theCGIHdl );
 } else {
// We weren't suspended, but still need to take care of the Apple event
// reply record.
 theErr = cgiAEComplete ( theCGIHdl );
 }
 
 return theErr;
}

/* Call the event completion function (cgiAEComplete) when resuming
     suspended Apple events. theReference must be a CGIHdl. */
pascal OSErr
CGIAEResumeComplete ( const AppleEvent *theAppleEvent,
 AppleEvent *theReply, long theReference )
{
 OSErr  theErr;
 
 theErr = cgiAEComplete ( (CGIHdl)theReference );
 
 return theErr;
}

/* Complete the CGI Apple event. theCGIHdl must be valid. */
static OSErr
cgiAEComplete ( CGIHdl theCGIHdl )
{
 OSErr  theErr;
    
 HLock ( (Handle)theCGIHdl );
 
 if ( (*theCGIHdl)->responseData != nil ) {
// If the user's "MyCGIProcess" function set the responseData properly, return it.
 theErr = AEPutParamPtr ( &((*theCGIHdl)->replyEvent),
 keyDirectObject, typeChar,
 (Ptr)((*theCGIHdl)->responseData),
 (*theCGIHdl)->responseSize );
 } else {
// If the user's "MyCGIProcess" failed to set the responseData properly,
// return an error header.
 theErr = AEPutParamPtr ( &((*theCGIHdl)->replyEvent),
 keyDirectObject, typeChar, (Ptr)gHTTPHeaderErr,
 gHTTPHeaderErrSize );
 }
 
 HUnlock ( (Handle)theCGIHdl );
    
 cgiDisposeHandle ( theCGIHdl );
 
 return theErr;
}

Using Preallocated Threads

One thing to be concerned about is overloading on threads. Having a handful of threads available can improve performance, but running dozens of threads can bog things down - especially in terms of memory usage, since each thread has its own stack allocated in the application heap. Because of this, creating threads can quickly eat up a significant chunk of memory. You can reduce this somewhat by calculating the maximum total space you will need for the thread stack and using that value in place of the default when allocating threads. However, memory use by threads will still be a significant matter.

A good strategy is to preallocate a limited number of threads and use only those. This has the double advantage of increasing the thread allocation speed and reducing heap fragmentation. In your application initialization sequence, you'll need to allocate a pool of threads after confirming that the Thread Manager is available.

// Pre-allocate the required number of threads.
// kStartupThreadsPreallocate is a constant defined in "MyConfiguration.h"
// which I use to define the total number of threads to preallocate
 CreateThreadPool ( kCooperativeThread,
 kStartupThreadsPreallocate, nil );

You will want to use a wrapper call to NewThread to put the current thread to sleep if there aren't any available threads in the pool. This is done so that one of the active threads may have time to complete, at which point the finishing thread will "wake up" the sleeping thread, allowing it to continue on from the point where it went to sleep, with a thread (the one that just finished) now available from the preallocated pool.

/* Allocate a new thread from the existing pool of threads.
    If there are no threads available, yield to other threads until one finishes.
    The Thread Manager must be available for this function to work. */
OSErr
MyNewThreadFromPool ( ThreadEntryProcPtr threadEntry,
 void * threadParam, void ** threadResult,
 ThreadID * threadMade )
{
 OSErr     theErr;
 short     threadsFree;
 ThreadID  currentThread;
 
 theErr = GetFreeThreadCount ( kCooperativeThread,
 &threadsFree );
 if ( theErr == noErr ) {
 theErr = GetCurrentThread ( &currentThread );
 }
 if ( (theErr == noErr) && (threadsFree == nil) ) {
// Put the current thread to sleep, to be woken up when a thread becomes available.
 gThreadSleeper = currentThread;
 theErr = SetThreadState ( currentThread,
 kStoppedThreadState, nil );
 }
 if ( theErr == noErr ) {
// Install the new thread using a premade thread from the pool.
 theErr = NewThread ( kCooperativeThread,
 threadEntry, threadParam, nil,
 kFPUNotNeeded + kUsePremadeThread,
 threadResult, threadMade );
 }
 if ( theErr == noErr ) {
// Set the termination function for the thread.
 SetThreadTerminator ( *threadMade,
 myThreadTermination, nil );
 
// Increment the total number of sub-threads.
 ++gThreadTotal;
 
// Decrease the sleep ticks so we'll take more processing time.
 gSleepTicks = kSleepTicksWhenBusy;
 }
 
 return theErr;
}

A thread termination callback procedure is used to wake up the sleeping thread when another thread is finished.

/* The Thread Manager must be available for this function to work. */
pascal void
myThreadTermination ( ThreadID threadTerminated, void
 *terminationProcParam )
{
 if ( gThreadSleeper != nil ) {
// Wake up the sleeping thread so that it may be called when other threads yield.
 theErr = SetThreadState ( gThreadSleeper,
 kReadyThreadState, nil );
 gThreadSleeper = nil;
 }
 
// Lower the count of sub-threads.
 --gThreadTotal;
 
 if ( gThreadTotal == nil ) {
// If there are no more threads, reset the sleep ticks to normal.
 gSleepTicks = kSleepTicks;
 }
}

When to Thread

After considering all this, you should ask yourself whether you really need to thread your Apple event handlers. The keys to answering this question are whether there are any points in the handler where it would be appropriate to yield the processing to other threads, and, more importantly, whether the handler is big and slow enough to see performance benefits from threading. Keep in mind that there is overhead and complexity added when you use cooperative threading.

As an example, I didn't thread my Random URL CGI because its response time (with rare exception) is under a second. To thread it would only add time to the total process without any real improvement in performance (not to mention increased memory requirements). On the other hand, a form-handling CGI I'm working on is threaded, because it will frequently have to talk (through Apple events) to other applications, which can slow things down appreciably (and waiting for a response is a great time to yield processing).

Further Considerations

If your application spawns threads from any threads apart from the main thread, you will need to maintain a queue of sleeping threads rather than just the one stored in this article's code. Another important consideration, that hasn't been covered here, is to make sure that WaitNextEvent is still periodically called if the main thread is put to sleep. You don't absolutely have to do that, but it is strongly recommended so that other applications and processes can have time to run. You may want to think about resetting the calling application's Apple event timeout timer when an event is taking a long time to process. Additionally, any CGI that wants to support the new "Send Partial" multi-stage reply mechanism in WebSTAR will need to make more advanced use of threading and Apple events.

Grant's CGI framework comes with project files for the CodeWarrior, THINK C and Symantec Project Manager environments.

Discussion mailing list: grantcgi@arpp.carleton.ca with the subject set to: help

Home page: http://arpp.carleton.ca/cgi/framework/

 
AAPL
$98.44
Apple Inc.
+0.06
MSFT
$43.64
Microsoft Corpora
-0.25
GOOG
$586.77
Google Inc.
+1.16

MacTech Search:
Community Search:

Software Updates via MacUpdate

Mellel 3.3.6 - Powerful word processor w...
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
LibreOffice 4.3.0.4 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
Freeway Pro 7.0 - Drag-and-drop Web desi...
Freeway Pro lets you build websites with speed and precision... without writing a line of code! With it's user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of... Read more
Drive Genius 3.2.4 - Powerful system uti...
Drive Genius is an OS X utility designed to provide unsurpassed storage management. Featuring an easy-to-use interface, Drive Genius is packed with powerful tools such as a drive optimizer, a... Read more
Vitamin-R 2.15 - Personal productivity t...
Vitamin-R creates the optimal conditions for your brain to work at its best by structuring your work into short bursts of distraction-free, highly focused activity alternating with opportunities for... Read more
Toast Titanium 12.0 - The ultimate media...
Toast Titanium goes way beyond the very basic burning in the Mac OS and iLife software, and sets the standard for burning CDs, DVDs, and now Blu-ray discs on the Mac. Create superior sounding audio... Read more
OS X Yosemite Wallpaper 1.0 - Desktop im...
OS X Yosemite Wallpaper is the gorgeous new background image for Apple's upcoming OS X 10.10 Yosemite. This wallpaper is available for all screen resolutions with a source file that measures 5,418... Read more
Acorn 4.4 - Bitmap image editor. (Demo)
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
Bartender 1.2.20 - Organize your menu ba...
Bartender lets you organize your menu bar apps. Features: Lets you tidy your menu bar apps how you want. See your menu bar apps when you want. Hide the apps you need to run, but do not need to... Read more
TotalFinder 1.6.2 - Adds tabs, hotkeys,...
TotalFinder is a universally acclaimed navigational companion for your Mac. Enhance your Mac's Finder with features so smart and convenient, you won't believe you ever lived without them. Tab-based... Read more

Latest Forum Discussions

See All

Become a Guardians of Galactic Peace Wit...
Become a Guardians of Galactic Peace With the New Spacefaring Sim, Kairobotica. Posted by Jessica Fisher on July 30th, 2014 [ permalink ] | Read more »
Soul Guardians: Age of Midgard Review
Soul Guardians: Age of Midgard Review By George Fagundes on July 30th, 2014 Our Rating: :: SO MUCH GRIND IT CRUNCHESUniversal App - Designed for iPhone and iPad Swords and trading cards are fun, right? So is Soul Guardians: Age of... | Read more »
NFL Fantasy Football App Redesigned Ahea...
NFL Fantasy Football App Redesigned Ahead of Upcoming 2014 Season Posted by Ellis Spice on July 30th, 2014 [ permalink ] | Read more »
Matter Review
Matter Review By Jennifer Allen on July 30th, 2014 Our Rating: :: ORIGINAL PHOTO MANIPULATIONUniversal App - Designed for iPhone and iPad Matter lets you add geometric 3d shapes to your images and manipulate things so each image... | Read more »
Note Review
Note Review By Jennifer Allen on July 29th, 2014 Our Rating: :: TOO SIMPLEiPhone App - Designed for the iPhone, compatible with the iPad Note is a note taking app that’s a little too short on features to be worth its asking price... | Read more »
Chainsaw Warrior Goes on Sale & Ther...
Chainsaw Warrior Goes on Sale & There’s a Chance to Win a Copy of the Original Board Game Posted by Jennifer Allen on July 29th, 2014 [ permalink | Read more »
It Came From Canada: Tiny Tower Vegas
If you go to a casino, you might make a lot of money. If you run a casino, you’re guaranteed to make a lot of money. The choice seems pretty obvious. So while waiting for your shady real estate deals to move forward, get prepared with Tiny Tower... | Read more »
Z Hunter Review
Z Hunter Review By Lee Hamlet on July 29th, 2014 Our Rating: :: RIGHT ON TARGETUniversal App - Designed for iPhone and iPad While it might not necessarily break new ground, Z Hunter has enough tricks up its sleeve to ensure that... | Read more »
Huge Update Comes To Duet, Adding 48 New...
Huge Update Comes To Duet, Adding 48 New Stages Posted by Jennifer Allen on July 29th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Sharknado: The Video Game Available Now....
Sharknado: The Video Game Available Now. Seriously. Posted by Rob Rich on July 29th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »

Price Scanner via MacPrices.net

13-inch 2.5GHz MacBook Pro on sale for $999,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $999.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $100 off MSRP. Price is... Read more
WaterField Unveils 15″ Outback Solo & 13″...
Hard on the heels of Apple’s refreshed MacBook Pro Retina laptops announcement, WaterField Designs has unveiled a 15-inch version of the waxed-canvas and leather Outback Solo and a 13-inch version of... Read more
New Roxio Toast 12 Delivers Digital Media Pow...
Roxio Toast 12 is a hub for sharing digital media to virtually any platform or device. has introduced two new additions to its Roxio Toast product family – Roxio Toast 12 Titanium and Roxio Toast 12... Read more
The lowest prices on leftover Retina MacBook...
Best Buy has dropped prices on leftover 13″ and 15″ Retina MacBook Pros by up to $300 off original MSRP on their online store for a limited time. Choose free local store pickup (if available) or free... Read more
Apple Updates MacBook Pro with Retina Display...
Apple today updated its MacBook Pro with Retina display with faster processors and double the amount of memory in both entry-level configurations. MacBook Pro with Retina display features a Retina... Read more
Up to $250 price drop on leftover 15-inch Mac...
B&H Photo has dropped prices on 2013 15″ Retina MacBook Pros by as much as $250 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.3GHz Retina MacBook Pro: $2349... Read more
Updated MacBook Pro Price Trackers
We’ve updated our MacBook Pro Price Trackers with the latest information on prices, bundles, and availability on the new 2014 models from Apple’s authorized internet/catalog resellers as well as... Read more
Apple updates MacBook Pros with slightly fast...
Apple updated 13″ and 15″ Retina MacBook Pros today with slightly faster Haswell processors. 13″ models now ship with 8GB of RAM standard, while 15″ MacBook Pros ship with 16GB across the board. Most... Read more
Apple drops price on 13″ 2.5GHz MacBook Pro b...
The Apple Store has dropped their price for the 13″ 2.5GHz MacBook Pro by $100 to $1099 including free shipping. Read more
Apple drops prices on refurbished 2013 MacBoo...
The Apple Store has dropped prices on Apple Certified Refurbished 13″ and 15″ 2013 MacBook Pros, with model now available starting at $929. Apple’s one-year warranty is standard, and shipping is free... Read more

Jobs Board

Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**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
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**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 (ASC) - Apple (...
**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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.