TweetFollow Us on Twitter

Sprocket Threads
Volume Number:10
Issue Number:12
Column Tag:Enhancing Sprocket

Related Info: Apple Event Mgr SCSI Manager

Adding Threads To Sprocket

Programming like you had a “real” OS

By Steve Sisak, Articulate Systems

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

About the Author

Steve Sisak - Steve lives in Cambridge, MA, with three Macintoshes, two Newtons, and two neurotic cats. He referees Lacrosse games, plays hockey, drinks beer, and searches for the perfect vindaloo. He also finds time to work on a speech recognition system for Articulate Systems during the day, a multithreaded communication server and thread-savvy studio library at night, and a variety of odd jobs the rest of the time.

Introduction

Last month, in Randy Thelan’s article “Threading Your Apps”, you learned a bit about the theory behind the Threads Manager and how to call its routines. This month, we’ll skip past the theory and focus on how you can combine the Threads Manager and the AppleEvent Manager, with the help of a couple of small libraries, to make the job of writing a modern Macintosh application much easier. Rather than cover every aspect of the Threads Manager, we will concentrate on a few key features that can really save you time. In fact, if you’re using the libraries as-is, you may never need to call the Threads Manager directly at all. The libraries, AEThreads and Futures, are useful as both stand-alone libraries and as non-trivial examples of multi-threaded code. In addition, in what I hope continues as a good trend, I have integrated them into the MacTech application framework, Sprocket. We’ll start with a quick overview of the libraries, continue with a description of how to use them, and finally delve into the details of how they’re implemented. Even if you only plan to use the libraries as-is, this section should help you to understand threaded programming and may also help you avoid traps and pitfalls I’ve already encountered.

The application model we’ll be using is a threaded extension of the fully factored application that Apple has been begging us to implement for the last few years - it is split into a user interface portion and a server portion which communicate with each other using AppleEvents. The difference is that, instead of handling each event sequentially, the AEThreads library allows the server portion of the application to handle multiple events concurrently and asynchronously, each in a separate thread of execution. It takes care of all of the bookkeeping involved with spawning and cleaning up after the threads, suspending and resuming the AppleEvents, and reporting errors to the AppleEvent Manager. Further, the Futures library provides routines that allow you to write client code in a traditional linear style, without idle procs, and to ask multiple questions of multiple servers simultaneously. And, even better, the Threads and AppleEvent managers do all of the hard work for you!

I first got interested in threaded AppleEvent code while working on a credit card validation server (Credit Now!, Appropriate Solutions). The intent was to develop a small application which could receive information about a purchase, dial up the credit card network, process the transaction and return an authorization code. Sending an AppleEvent seemed like the logical thing to do. The problem was that, with the phone call involved, the event took approximately 45 seconds to generate a reply. Further, during that time, we had to service the serial port, run a communication protocol which was best expressed as a loop, and service the user. (After all, no user would tolerate their machine locking up for 45 seconds.) This sounded like a good job for the then just-released Threads Manager. I’m not sure where I got the idea of spawning threads using AppleEvents, but I’m pretty sure it involved beer. Anyway, I’ve used the code in several products since and have been very happy with it.

A word about the code. One of my pet peeves with example code has been that handling errors is left as an exercise for the programmer. This is not the case with AEThreads and Futures. I’ve made every attempt to ensure that the libraries meet commercial quality code standards. While I must make all the usual disclaimers, I use this code in shipping products, so I’ll fix any bugs you report. I have provided the full source to offer you some insight into some nuances of threaded programming and to allow you advanced programmers out there to fine tune them. (I use slightly different versions to support TCL, MacApp, and PowerPlant exception handling.) Also, until Sprocket has a true Thread class (coming soon), you may want to edit the SwitchIn and SwitchOut routines to save additional context unique to your application.

You may also notice that this article makes no mention whatsoever (except in this paragraph) of preemptive threads, semaphores, critical sections or a number of other things you may have heard of in your operating systems class. This is intentional. This article and code are intended to save you time. Preemptive threads are not supported on the PowerPC. Having them in your system means you have to think about things like semaphores, resource contention, deadly embrace, etc. This does not save you time. Enough said.

So, without further ado, let’s get to the meat of the article.

AEThreads

The first thing you need to do to implement a multi-threaded server is figure out how to spawn a new thread. If you’ve been reading the Threads Manager documentation and Randy’s article last month, you know that to start a new thread, all you have to do is call NewThread(), right? How do you get parameters to it? How do you get results back? You dutifully pack up all the information into a big structure in a local variable and pass its address as the threadParam to NewThread. You pass the address of another variable as the threadResult parameter. But when you run your code, you discover, after many trips to Macsbug, that the routine that called NewThread() has long since returned by the time the thread actually runs (leaving threadParam and threadResult pointing into hyperspace). There’s got to be an easier way to get information to a thread.

Well, how about just sending it an AppleEvent? OK, a thread isn’t an application, so you can’t send an event to it directly, but using the AEThreads library you can send an event to yourself and have it handled by a thread. In fact, AEThreads has only one public routine - AEInstallThreadedEventHandler(). To use it, just call it where you would have called AEInstallEventHandler() to install your handler for the event. AEInstallThreadedEventHandler() takes the same parameters as AEInstallEventHandler (except isSysHandler, since we need our applications’s A5 world) plus the ThreadOptions and stack size parameters from NewThread. When an event comes in, AEThreads automatically suspends the event, creates a new thread and calls your handler from within it. When your handler returns, it cleans up, resumes the event, and returns the reply to the sender. Notice that if the Threads Manager is not present and you don’t do anything that requires multiple events to be handled simultaneously, you can just call AEInstallEventHandler() instead of AEInstallThreadedEventHandler() and your application will still run, except that incoming events will be handled synchronously.

Yielding

Now that we have all of our AppleEvents handled in separate threads - we’re done, right? Well, not quite. Recall that we’re running in a cooperative multitasking environment. This means that it is our responsibility to give CPU time to other threads; if we don’t, then our thread will finish synchronously, completely missing the advantage of using a thread to handle the event.

The Threads manager provides a number of routines for scheduling thread execution. The simplest of these is YieldToAnyThread(), which you can call at any time you think would be good to give someone else some CPU time. The important thing to note is that, unlike WaitNextEvent(), YieldToAnyThread() is a very inexpensive call, so you shouldn’t be afraid to call it often. (You should, however, have a thread-aware event loop, like the one Dave Falkenburg put into Sprocket, to make sure your main thread doesn’t call WaitNextEvent too often).

Blocking I/O

Another technique for yielding CPU time involves blocking I/O routines. These are routines which look like high level synchronous I/O routines, except that they know enough to block your thread and give up the CPU while the I/O is executing. For instance, a blocking version of FSRead() might look like this:


/* 1 */
pascal OSErr ThreadFSRead(short refNum,long *count,void *buffPtr, long 
timeout)
{
 ParamBlockRec pb;

 pb.ioParam.ioCompletion = nil;
 pb.ioParam.ioRefNum = refNum;
 pb.ioParam.ioBuffer = buffPtr;
 pb.ioParam.ioReqCount = *count;
 pb.ioParam.ioPosMode = 0;
 pb.ioParam.ioPosOffset = 0;

 timeout += TickCount();

 PBReadAsync(&pb);

 while (pb.ioParam.ioResult > 0 && TickCount() <= timeout)
 {
 YieldToAnyThread();
 }

 *count = pb.ioParam.ioActCount;
 return pb.ioParam.ioResult;
}

Now, replacing calls to FSRead() with ThreadFSRead() will allow other threads to execute while the I/O is in progress. We have also added a timeout mechanism which is useful for serial I/O. Note that this technique requires very little modification to existing code. Further, Apple promises to add blocking I/O to the Mac OS in the future. Writing your code in this way prepares you for the future. You may also notice that we didn’t use any of the fancy Thread Manager routines to suspend the thread, etc. This is because it is possible for the asynchronous I/O call to complete while we were trying to put the thread to sleep, leaving it stuck that way. While there are ways around this, it’s not worth the hassle. YieldToAnyThread() is cheap, and this technique gives a robust timeout mechanism for free. (If you didn’t understand that, don’t worry, you don’t need to).

It is important to note that, depending on the driver you’re calling, the call to PBReadAsync() may complete synchronously, resulting in no yield. This is true for floppy and pre-SCSI Manager 4.3 hard disk reads. In these cases you may want a more sophisticated routine which reads blocks, say 4k, yielding between each block. Also, in the case of the serial port, you may want to issue a control call first to see how many bytes are actually waiting. But these are topics for another article

Futures

One of the biggest hassles of writing AppleEvent-based client-server code (or any communications code in the Macintosh) is that you must rewrite any time-consuming algorithm into a state machine built around idle procs. This is because you must constantly service the event loop by calling WaitNextEvent(). This is tedious, time consuming, error prone, and generally not fun. If you’ve got some spare time you just really want to waste, try implementing the ZModem protocol this way.

Enter the Threads Manager. Now you can just spawn a thread, implement your algorithm as a series of nested loops (just like a “real” operating system), and sprinkle a few calls to YieldToAnyThread() through your code. This works great if you’re talking to a serial port, but what if you want to send AppleEvents to another application (or yourself) in the loop. Then you’re back to writing state machines. (Or some very complicated Apple Event idle procs)

In his article “Threaded Communication with Futures” in develop issue 7, Michael Gough described a particularly elegant solution to this problem, called the Futures Package, which provided a blocking I/O style interface to the AppleEvent manager based on the Threads Manager’s predecessor, the Threads Package. In fact, it goes even further by performing a kind of delayed evaluation which allows the client code to send events to multiple servers without waiting until it needs to use a reply which hasn’t returned yet. Unfortunately, support for the Futures Package was discontinued when the Threads Package was replaced by the Threads Manager. Apple even pulled the example code off the develop CD.

Last December I was talking to Brad Post and Eric Anderson about the Threads Manager at a PowerPC training session and asked what ever became of the Futures Package. I was told that, while it was really cool, nobody had gotten the time to update it and it didn’t look like it was going to happen any time soon. I begged. The next day Brad gave me some source that hadn’t been compiled yet to see if I could get it working. I promised to try. After a couple of late nights and some serious hair pulling trying to find a missing ThreadEndCritical(), (I later removed all the critical section code because the AppleEvent manager can’t be called at interrupt time and nobody else has any business looking at the data anyway) I got the package working. I give this long-winded explanation because the small amount of code you see here is the result of a lot of people’s work and I’m not entirely sure who gets credit for what, but the end result is extremely cool, elegant, and useful.

The key function in the Futures package is Ask(). Ask() functions like AESend(), except that it returns immediately. The trick is that its reply AppleEvent is actually a future (or thunk to you Scheme programmers, and to resolve Randy’s dangling pun from last month). As long as you don’t attempt to extract any data from it, your code continues to execute normally. However, if you try to extract information (using AEGetParamPtr() or any of its friends) before the reply has actually returned, the Futures library will suspend execution of your thread until the reply actually returns. The result is that, to your thread, it looks like AEGetParamPtr() returned immediately too, but in fact the CPU was transparently given to other tasks until your request could be fulfilled. Important: If you want to be able to process incoming events during a call to Ask(), make sure you’re not calling it from the main thread. This is what AEThreads is designed to help you do - just install your server routine as a threaded handler.

Disclaimer

You may discover, after reading the code, that the functionality of the Futures library really belongs in the AppleEvent manager. It does. In fact, I believe that adding kAEFutureReply as a send mode in AESend() would take care of it at the API level. (Is anyone at Apple listening?) The source code is provided here because I cannot guarantee that it is entirely bug free. However, you should be very cautious in modifying it. It uses a pair of special handlers in the AppleEvent manager which were added to support the original futures package; they’re not documented for third-party use, and I strongly urge that you not use them for anything else. There is also a design limitation if the reply to your event is never received (because of a lost network connection or some other reason) you will not get a timeout error and your thread will stay suspended indefinitely. I plan to fix this in the future, and it may not be a big problem in many cases, but please be aware of it. If anyone out there wants to add this functionality, I will gladly include it in a future release.


/* 2 */
AEThreads Reference

AEInstallThreadedEventHandler

pascal OSErr AEInstallThreadedEventHandler(
 AEEventClass theAEEventClass,
 AEEventID theAEEventID,
 AEEventHandlerProcPtr handler,
 long handlerRefcon,
 ThreadOptions options,
 Size stacksize);

AEInstallThreadedEventHandler is used to install a handler for an AppleEvent which is to be handled in a thread. The first four parameters are the same as for AEInstallEventHandler(), the last two are passed to NewThread() to create a thread for your handler. You may use any of the parameters documented in the threads manager except kNewSuspend (which would cause your handler to never be called).

Futures Reference

For a full description of the futures library, see Michael Gough’s develop article. A quick summary is provided here for your convenience.

InitFutures


/* 3 */
pascal OSErr InitFutures(void);

Call InitFutures() once at the beginning of your program to initialize the futures package.

Ask


/* 4 */
pascal OSErr Ask(AppleEvent* question, AppleEvent* answer);

Call Ask() instead of AESend() to send an AppleEvent. The trick to efficient code is to call Ask() as early as possible and look at the result as late as possible in order to give the server the maximum amount to time to process your request.

IsFuture


/* 5 */
pascal Boolean IsFuture(AppleEvent* message);

Call IsFuture() to test if the reply from a call to Ask() is a future without stopping your thread if it is. If IsFuture() returns true, the reply hasn’t returned yet and you should probably go work on something else.

BlockUntilReal


/* 6 */
pascal OSErr BlockUntilReal(AppleEvent* message);

Call BlockUntilReal() to force the current thread to block until the reply actually comes back.

How AEThreads Works

The AEThreads library is implemented as a chain of three main routines (AEInstallThreadedEventHandler(), SpawnAEThread() and AEThread()) and a pair of custom thread switchers.

AEInstallThreadedEventHandler() is a fairly simple routine. Basically, it allocates a pointer in the application heap, copies its parameters there and calls AEInstallEventHandler() for the event specified with SpawnAEThread() as the handler and the pointer as the refcon.

When an event comes in, SpawnAEThread() is invoked. Its responsibility is to get the new thread started. First, it copies the parameters needed by the new thread into a local structure and then calls NewThread() with AEThread() as the threadProc and the address of the parameter structure as the threadParam. Next it enters a yield loop, yielding the thread it just created and watching a flag in the parameter block for a signal that the thread has started. This is necessary because, although the thread has been created, the threadProc hasn’t been called yet and the thread parameters are in a local variable. If we returned to the AppleEvent manager now, the threadParam would be a dangling pointer when the thread actually ran. This can also be avoided by allocating the threadParam as a pointer or handle. I have chosen not to do this here, however, because I don’t want to fragment the heap more than necessary and the semaphore structure allows us to get an error message from the threadProc if it has difficulty getting itself up and running. (OK, I mentioned semaphore again, but at least you didn’t have to deal with it).

AEThread() is the wrapper routine which actually calls your handler. The first thing it does is copy its parameters into local variables so they’ll still be around when SpawnAEThread() returns. Next it installs a pair custom switcher which saves and restore any global context unique to used to our thread. Metrowerks C++ stores a linked list of stack-based object whose destructors must be called in compiler-generated global variable __local_destructor_chain. You must save and restore it here or you will be very sorry. Also if you are using a class library with exception handling, you would save and restore the failure stack here (gTopHandler for MacApp; gTopHandler, gLastError, and gLastMessage for TCL 1.x). You may also want to save thePort, etc. This is necessary so that if a failure occurs in the thread, no handlers from outside the thread will be called. Now we suspend the event, clear the semaphore, and enter a yield loop so SpawnAEThread() can return to the AppleEvent manager.

The next time we get time, we are on our own. We now call the user’s handler, wrapped in a failure handler, if available. If an error is reported here, we must manually pack the error code into the reply AppleEvent before returning. Next we resume the event and return to the Apple Event Manager. This will let the thread die and cause the reply event to be returned to the sender.

OK, it’s a little confusing, but just remember that it was done here so you won’t have to

How Futures Works

The futures code is based around two undocumented (until now) callbacks in the AppleEvent manager which are accessed via AEInstallSpecialHandler(). One (‘blck’) [Randy, can we get these puppies some real names] is called whenever there is an attempt to read data from a reply event which hasn’t arrived yet. The other ‘unbk’ is called whenever a reply arrives. We also use the refcon (‘refc’) attribute of the event to store a handle to a list of the threads currently waiting on a reply for this event.

InitFutures() simply installs DoThreadBlock() and DoThreadUnBlock() as the ‘blck’ and ‘unbk’ handlers, respectively.

If someone tries to extract data from a reply which is really a future, DoThreadBlock() is called by the AppleEvent manager. DoThreadBlock() then checks the ‘refc’ attribute of the event for a list of blocked threads. If it finds one, it adds the current thread to it; otherwise it creates a new list containing the current thread and puts it back in the reply. In either case it then suspends the thread which caused it to be called.

Whenever an incoming reply is detected, DoThreadUnBlock() is called for the event. If the refcon of the event contains a blocked thread list, DoThreadUnBlock() makes all of the threads in the list eligible for execution.

Ask() is simply a wrapper which calls AESend() synchronously with a timeout of 0 ticks, causing it to time out immediately and suppresses the timeout error. The reply will eventually come in, however, and be properly reported.

IsFuture() temporarily replaces DoThreadBlock() with a handler which does nothing and tests for a errAEReplyNotArrived error.

BlockUntilReal() just tries to extract a nonexistent parameter, ‘gag!’, from the event, forcing a block if the reply isn’t real.

The Sample Code

The demo works as follows: Selecting “Ping” from the Debug menu sends an AppleEvent back to the application which calls the HandlePing() function in a thread. It brings up a PPCBrowser window asking you to select this or another copy of Sprocket as a target. It then enters a loop sending ping events to the target. For each ping, the target extracts the direct object from the event, stuffs in a reply and beeps to let you know it’s doing its job. Selecting Ping2 does the same thing, but lets you choose two separate targets.

To see how this all works, take a look at the latest version of Sprocket and check out the files AEThreads.h and .c, Futures.h and .c, and FuturesDemo.h and.c. FuturesDemo.h is excerpted from Michael’s develop sample code, updated to use AEThreads. There are also a few lines added to App.cp to set up the libraries and add menu handlers.

In Conclusion...

Well, that’s about it. I hope both this article and the code are useful to you. In the future, I would like to continue to add technology to Sprocket. The next logical candidates are a simple Thread class, and an exception library (the other thing I can’t live without). It’s 3am and there’s too much blood in my caffeine system, so good night...

AEThreads.h


/* 7 */
// AEThreads.h
//
// Copyright © 1993-94 Steve Sisak
// 
// License is granted to use, modify, make derivative works, and 
// duplicate this code at will, so long as this notice remains intact.
//

#ifndef __AETHREADS__
#include "AEThreads.h"
#endif
#ifndef __ERRORS__
#include <Errors.h>
#endif
#ifndef __APPLEEVENTS__
#include <AppleEvents.h>
#endif
#if __MWERKS__
#if defined(powerc) || defined(__powerc)
#include <CPlusLibPPC.h>
#else
#include <stdlib.h>
#include <CPlusLib68k.h>
#endif
#endif

typedef struct AEThreadDesc  AEThreadDesc;
typedef struct AEThreadParam AEThreadParam;
typedef struct AESwapData    AESwapData;

struct AEThreadDesc// Kept in the OS refcon
{
 AEEventHandlerUPP handler; // The real handler
 long   refcon;  // The real refcon
 Size   stackSize; // Stack size for handling event
 ThreadOptions   options; // Thread options for event
 ThreadID holder;// used as a semaphore
};

struct AEThreadParam // Used in spawning
{
 const AppleEvent* event;
 AppleEvent*reply;
 AEThreadDesc*   desc;
 ThreadID thread;
 OSErr  result;
};

struct AESwapData
{
 void*  fTopHandler; // Top failure handler

#ifdef __MWERKS__
 DestructorChain*fStaticChain;//
#endif
};

pascal void SwitchInHandler(ThreadID threadBeingSwitched, 
 void *switchProcParam);
pascal void SwitchOutHandler(ThreadID threadBeingSwitched,
  void *switchProcParam);
pascal OSErrSpawnAEThread(const AppleEvent *theAppleEvent,
   AppleEvent *reply, 
 long handlerRefcon);
pascal long AEThread(AEThreadParam* parms);

AEEventHandlerUPP gSpawnAEThreadUPP = nil;


#pragma segment foobar

AEInstallThreadedEventHandler

pascal OSErr AEInstallThreadedEventHandler(
 AEEventClass    theAEEventClass,
 AEEventIDtheAEEventID,
 AEEventHandlerUPP proc,
 long   handlerRefcon,
 ThreadOptions   options,
 Size   stacksize)
{
 AEThreadDesc* desc = (AEThreadDesc*) 
 NewPtr(sizeof(AEThreadDesc));
 OSErr    err  = MemError();
 
 if (gSpawnAEThreadUPP == nil)
 {
 gSpawnAEThreadUPP = NewAEEventHandlerProc(SpawnAEThread);
 }
 
 if (err == noErr)
 {
 desc->handler = proc;
 desc->refcon  = handlerRefcon;
 desc->stackSize = stacksize;
 desc->options = options;
 desc->holder  = kNoThreadID;

 err = AEInstallEventHandler(theAEEventClass, 
 theAEEventID, gSpawnAEThreadUPP, 
 (long) desc, false);
 }
 
 return err;
}

#pragma segment AEThread

SwitchInHandler

pascal void SwitchInHandler(ThreadID threadBeingSwitched, void *switchProcParam)
{
 AESwapData* swap = (AESwapData*) switchProcParam;

#ifdef __MWERKS__
 swap->fStaticChain = __local_destructor_chain;
#endif
}

SwitchOutHandler

pascal void SwitchOutHandler(ThreadID threadBeingSwitched, void *switchProcParam)
{
 AESwapData* swap = (AESwapData*) switchProcParam;

#ifdef __MWERKS__
 __local_destructor_chain = swap->fStaticChain;
#endif
}


#define ErrCheck(label, result)  if ((result) != noErr) goto label;

AEThread

pascal long AEThread(AEThreadParam* parms)
{
 AppleEvent event; // Original parameters we care about
 AppleEvent reply;
 AEThreadDesc  * desc;
 OSErr  err;
 OSErr  procErr;
 AESwapData swap;

 event = *parms->event;   // copy these into our own stack frame
 reply = *parms->reply;
 desc  =  parms->desc;

#if 0 
 myTopHandler = gTopHandler;// Save global failure handler
 gTopHandler  = nil; // don’t let failures propagate outside
#endif

 ErrCheck(punt, err = SetThreadSwitcher(kCurrentThreadID,
  SwitchInHandler,  &swap, true));
 ErrCheck(punt, err = SetThreadSwitcher(kCurrentThreadID, 
  SwitchOutHandler, &swap, false));
 ErrCheck(punt, err = AESuspendTheCurrentEvent(&event));

 parms->result = noErr;   // Let caller know we’re ready

 // At this point, we need to let our caller return

 while (desc->holder != kNoThreadID)
 {
 YieldToThread(desc->holder);
 }

 // We are now on our own
 
 procErr = err = CallAEEventHandlerProc(desc->handler, 
 &event, &reply, desc->refcon);

 // Since the event was suspended, we need to stuff the error code ourselves
 
 // note that there’s not much we can do about reporting errors beyond 
here
 
 err = AEPutAttributePtr(&reply, keyErrorNumber, 
 typeShortInteger, &procErr, 
 sizeof(procErr));

#if qDebug
 if (err)
 ProgramBreak("\pAEPutAttributePtr failed installing error code - very 
bad");
#endif

 err = AEResumeTheCurrentEvent(&event, &reply,
 kAENoDispatch, 0);// This had better work

#if qDebug
 if (err)
 DebugStr("\pAEResumeTheCurrentEvent failed - very bad");
#endif

#if 0
 gTopHandler = myTopHandler;// Restore global failure handler
 myTopHandler = nil; // Keep terminator from firing handlers
#endif

punt:
 parms->result = err;
 return nil;
}

#pragma segment Spawn

SpawnAEThread

pascal OSErr SpawnAEThread(const AppleEvent *event, 
 AppleEvent *reply, long handlerRefcon)
{
 AEThreadParam param;
 
 param.event  = event;
 param.reply  = reply;
 param.desc  = (AEThreadDesc*) handlerRefcon;
 param.thread = kNoThreadID;

 if (!param.desc)
 {
 param.result = paramErr;
 }
 else
 {
 // make sure no-one else is trying to start a handler   
 while (param.desc->holder != kNoThreadID)   
 {
 YieldToAnyThread();
 }
 
 if ((param.result = 
 GetCurrentThread(&param.desc->holder)) == noErr)
 // Grab the semaphore
 {
 param.result = NewThread(kCooperativeThread,
 (ThreadEntryProcPtr) &AEThread,
 &param,
 param.desc->stackSize,
 param.desc->options,
 nil,
 &param.thread);
 
 if (param.result == noErr)
 {
 param.result = 1;
 
 do
 {
 YieldToThread(param.thread);
 }
 while (param.result == 1); // Wait for thread 
 // to pick up parameters
 }
 }
 
 param.desc->holder = kNoThreadID; // release any claims we have
 }
 
 return param.result;
}

Futures.c


/* 8 */
/*
 File:  Futures.c

 Copyright: © 1993 by Apple Computer, Inc., all rights reserved.
 © 1993-1994 by Steve Sisak, all rights reserved.

*/

#include "Futures.h"
#include <Threads.h>
#include <GestaltEqu.h>

pascal OSErrIsFutureBlock(AppleEvent* message);
pascal OSErrDoThreadBlock(AppleEvent* message);
pascal OSErrDoThreadUnblock(AppleEvent* message);

#define kAERefconAttribute'refc'
#define kAENonexistantAttribute  'gag!'
#define kImmediateTimeout 0

struct ThreadList
{
 short  numThreads;
 ThreadID threads[1];
};

typedef struct   ThreadList ThreadList, 
 *ThreadListPtr, **ThreadListHdl;

#define sizeofThreadList(numthreads) \
 (sizeof(ThreadList) + ((numthreads)-1)*sizeof(ThreadID))

typedef pascal OSErr (*AESpecialHandlerProcPtr)
 (AppleEvent *theAppleEvent);

enum {
 uppAESpecialHandlerProcInfo = kPascalStackBased
  | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(AppleEvent*)))
};

#if USESROUTINEDESCRIPTORS
typedef UniversalProcPtr AESpecialHandlerUPP;

#define CallAESpecialHandlerProc(userRoutine,      \
 theAppleEvent, reply, handlerRefcon)\
 CallUniversalProc((UniversalProcPtr)(userRoutine), \    
 uppAESpecialHandlerProcInfo, (theAppleEvent),     \
 (reply), (handlerRefcon))
#define NewAESpecialHandlerProc(userRoutine)       \
 (AESpecialHandlerUPP)NewRoutineDescriptor(  \
 (ProcPtr)(userRoutine),  \
 uppAESpecialHandlerProcInfo, GetCurrentISA())
#else
//typedef AESpecialHandlerProcPtr AESpecialHandlerUPP;
typedef ProcPtr AESpecialHandlerUPP;

#define CallAESpecialHandlerProc(userRoutine,      \
 theAppleEvent, reply, handlerRefcon)\
 (*(userRoutine))((theAppleEvent), (reply), (handlerRefcon))
#define NewAESpecialHandlerProc(userRoutine)       \
 (AESpecialHandlerUPP)(userRoutine)
#endif

AESpecialHandlerUPP gDoThreadBlockUPP= nil;
AESpecialHandlerUPP gDoThreadUnblockUPP= nil;
AESpecialHandlerUPP gIsFutureBlockUPP= nil;


InitFutures
pascal OSErr InitFutures(void)
{
 OSErr  err;
 long aResponse;
 
 gDoThreadBlockUPP = NewAESpecialHandlerProc(DoThreadBlock);
 gDoThreadUnblockUPP = NewAESpecialHandlerProc(DoThreadUnblock);
 gIsFutureBlockUPP = NewAESpecialHandlerProc(DoThreadBlock);
 
 err = Gestalt(gestaltThreadMgrAttr, &aResponse);
 
 if (err == noErr)
 err = AEInstallSpecialHandler('blck', gDoThreadBlockUPP,
  false);
 if (err == noErr)
 err = AEInstallSpecialHandler('unbk', 
 gDoThreadUnblockUPP, false);

 return err;
}

DoThreadBlock

pascal OSErr DoThreadBlock(AppleEvent* message)
{
 OSErr  err;
 DescType actualType;
 Size   actualSize;
 ThreadListHdl threadList;
 ThreadID currentThread;
 
 //Apparently the current thread needs to access some information, which 

 //is really a future.  We need to see if there is already a list of 
threads
 //blocked on this message.  If there isn’t, create an empty list.  Add
 //the current thread to the list.  Sleep the current thread.

 err = GetCurrentThread(&currentThread);

 if (err == noErr)
 {
 err = AEGetAttributePtr(message, kAERefconAttribute,
 typeLongInteger, &actualType,
 (Ptr) &threadList, sizeof(threadList), 
 &actualSize);

 if (err == errAEDescNotFound 
 || err == noErr 
 && !threadList)
 {
 // If we can’t find a waiting thread list, then create one containing 

 // just ourself and put it back in the message
 
 threadList = (ThreadListHdl) NewHandle(sizeofThreadList(1));
 
 err = MemError();
 
 if (err == noErr)
 {
 (**threadList).numThreads = 1;
 (**threadList).threads[0] = currentThread;
 
 err = AEPutAttributePtr(message, kAERefconAttribute, 
 typeLongInteger,
 (Ptr) &threadList, sizeof(threadList));
 }
 }
 else if (err == noErr)
 {
 // Otherwise just append ourself onto the existing list
 
 short numWaiting = (**threadList).numThreads;
 
 SetHandleSize((Handle) threadList, 
  sizeofThreadList(numWaiting+1));
 
 err = MemError();
 
 if (err == noErr)
 {
 (**threadList).threads[numWaiting] = currentThread;
 (**threadList).numThreads = ++numWaiting;
 }
 }
 }
 
 // If there was an error don’t block

 if (err == noErr)
 err = SetThreadState(currentThread, kStoppedThreadState, 
  kNoThreadID);

 return err;
}

DoThreadUnblock

pascal OSErr DoThreadUnblock(AppleEvent* message)
{
 OSErr  err;
 DescType actualType;
 Size   actualSize;
 ThreadStateblockedThreadState;
 ThreadListHdl   threadList;

 //This message has just turned real.  If there is a list of threads 
blocked 
 //because they tried to access the data, walk through the list of blocked
 //threads waking and deallocating the list element as you go.

 err = AEGetAttributePtr(message, kAERefconAttribute, 
 typeLongInteger, &actualType,
 (Ptr) &threadList, sizeof(threadList), 
 &actualSize);
 
 if (err == errAEDescNotFound)
 {
 //It’s possible that this unblocking handler will get called for ALL 
replies
 //to apple events, not just futures.  If that’s the case, then getting
 //the above error is not really an error.  Clear it and just return.
 
 err = noErr;
 }
 else if (err == noErr && threadList)
 {
 //If there’s a waiting list, make all threads in it ready for execution
 //We won’t report errors inside the loop because:
 //1) one of the threads might have been disposed of
 //2) there’s nothing we can do to recover at this point
 //3) the important thing is to wake up all remaining threads.

 ThreadID*nextThread = (**threadList).threads;
 short    numWaiting = (**threadList).numThreads;
 
 while (--numWaiting >= 0)
 {
 ThreadID blockedThread = *nextThread++;
 OSErr   err1 = GetThreadState(blockedThread,
    &blockedThreadState);
 
 if (err1 == noErr 
 && blockedThreadState == kStoppedThreadState)
 {
 err1 = SetThreadState(blockedThread,
 kReadyThreadState, kNoThreadID);
 }
 }
 
 // Now free the list handle (and take it out of the refCon just to be 
safe)
 
 DisposeHandle((Handle) threadList);
 
 threadList = nil;
 
 err = AEPutAttributePtr(message, kAERefconAttribute,
 typeLongInteger,
 (Ptr) &threadList, sizeof(threadList));

 } 

 return err;
}

BlockUntilReal

pascal OSErr BlockUntilReal(AppleEvent* message)
{
 OSErr  err;
 AERecord nonExistentParameter;
 
 err = AEGetParamDesc(message, kAENonexistantAttribute,
        typeAERecord, &nonExistentParameter);

 if (err == errAEDescNotFound)
 err = noErr;
 
 return err;
}

IsFuture

pascal Boolean IsFuture(AppleEvent* message)
{
 OSErr  err;
 AESpecialHandlerUPP oldBlockingProc;
 BooleanisFuture = false;
 
 err = AEGetSpecialHandler('blck', &oldBlockingProc, false);
 
 if (err == noErr)
 {
 err = AEInstallSpecialHandler('blck', gIsFutureBlockUPP,
  false);
 
 if (err == noErr)
 {
 if (BlockUntilReal(message) == errAEReplyNotArrived)
 {
 isFuture = true;
 } 
 
 err = AEInstallSpecialHandler('blck', oldBlockingProc,
 false);
 }
 }
 
 return isFuture;
}

IsFutureBlock

pascal OSErr IsFutureBlock(AppleEvent* /*message*/)
{
 return noErr;
}

Ask

pascal OSErr Ask(AppleEvent* question, AppleEvent* answer)
{
 //Send the question with an immediate timeout.

 OSErr err = AESend(question, answer, kAEWaitReply,
 kAENormalPriority,
        kImmediateTimeout, nil, nil);
 
 if (err == errAETimeout)
 err = noErr;

 return err;
}







  
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

iClock Pro 3.8 - Customize your menubar...
iClock Pro is a menu-bar replacement for Apple's default clock. iClock Pro is an update, total rewrite, and improvement to the popular iClock. Have the day, date, and time in different fonts and... Read more
VirtualBox 5.2.0 - x86 virtualization so...
VirtualBox is a family of powerful x86 virtualization products for enterprise as well as home use. Not only is VirtualBox an extremely feature rich, high performance product for enterprise customers... Read more
Dropbox 37.4.29 - Cloud backup and synch...
Dropbox is an application that creates a special Finder folder that automatically syncs online and between your computers. It allows you to both backup files and keep them up-to-date between systems... Read more
Google Chrome 62.0.3202.62 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Chromium 62.0.3202.62 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 62.0.3202.62: High CVE-2017-5124: UXSS with... Read more
Fantastical 2.4.3 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
Things 3.2.1 - Elegant personal task man...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
A Better Finder Attributes 6.06 - Change...
A Better Finder Attributes is the ultimate file-tweaking tool for OS X. It combines photo-shooting date and file date changing along with a few unique tricks of its own. Change EXIF Timestamps at... Read more
MacCleanse 6.0.5 - $29.95
MacCleanse is the product of thousands of hours of intense research and development. It meticulously scans all of the nooks and crannies of a computer for unnecessary junk that can take up huge... Read more
Smultron 10.0.2 - Easy-to-use, powerful...
Smultron 10 is an elegant and powerful text editor that is easy to use. You can use Smultron 10 to create or edit any text document. Everything from a web page, a note or a script to any single piece... Read more

Warhammer Quest 2 (Games)
Warhammer Quest 2 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Dungeon adventures in the Warhammer World are back! | Read more »
4 of the best Halloween updates for mobi...
Halloween is certainly one of our favorite times for mobile game updates. Many popular titles celebrate this spooky season with fun festivities that can stretch from one week to even the whole month. As we draw closer and closer to Halloween, we'... | Read more »
Fire Rides guide - how to swing to succe...
It's another day, which means another Voodoo game has come to glue our hands to our mobile phones. Yes, it's been an especially prolific month for this particular mobile publisher, but we're certainly not complaining. Fire Rides is yet another... | Read more »
Time Recoil (Games)
Time Recoil 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: Time Recoil is a top-down shooter where you kill to slow time, dominate slow motion gunfights, and trigger devastating special... | Read more »
Campfire Cooking (Games)
Campfire Cooking 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: | Read more »
Returner 77 (Games)
Returner 77 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Returner 77 is a cinematic space mystery puzzle game. You are in a giant alien spaceship hovering above Earth, after everything... | Read more »
Dune! guide - how to toe the line and ge...
Publisher Voodoo is at it again with an all new high score chaser -- Dune! In this fast-paced arcade game, you have to propel yourself along sand dunes, gaining enough momentum to jump above the line to score points, while making sure you have... | Read more »
The best deals on the App Store this wee...
Happy Tuesday, dear readers. Your favorite part of the week as officially arrived. It's time to take a look at the best deals in games. Things are admittedly a bit sparse, but there are a few diamonds in the rough to see you through if you're... | Read more »
Be the last person standing in Legacy of...
Yoozoo Games’ popular action MMO Legacy of Discord is getting a huge new update to celebrate its first anniversary. Perhaps the biggest change is the addition of an exciting survival mode titled Last Guardian. This new survival mode will pit you... | Read more »
Home Street guide - how to make friends...
From the creators of Food Street comes Home Street, a new simulation game that tasks you with building a social network and designing a beautiful home. It's a bit like The Sims, but you won't have to worry about the daily chores involved (feeding,... | Read more »

Price Scanner via MacPrices.net

13″ MacBook Pros on sale for up to $120 off M...
B&H Photo has 2017 13″ MacBook Pros in stock today and on sale for up to $120 off MSRP, each including free shipping plus NY & NJ sales tax only: – 13-inch 2.3GHz/128GB Space Gray MacBook... Read more
15″ MacBook Pros on sale for up to $200 off M...
B&H Photo has 15″ MacBook Pros on sale for up to $200 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: – 15″ 2.8GHz MacBook Pro Space Gray (MPTR2LL/A): $2249, $150... Read more
Roundup of Apple Certified Refurbished iMacs,...
Apple has a full line of Certified Refurbished 2017 21″ and 27″ iMacs available starting at $1019 and ranging up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free... Read more
Sale! 27″ 3.8GHz 5K iMac for $2098, save $201...
Amazon has the 27″ 3.8GHz 5K iMac (MNED2LL/A) on sale today for $2098 including free shipping. Their price is $201 off MSRP, and it’s the lowest price available for this model (Apple’s $1949... Read more
Sale! 10″ Apple WiFi iPad Pros for up to $100...
B&H Photo has 10.5″ WiFi iPad Pros in stock today and on sale for $50-$100 off MSRP. Each iPad includes free shipping, and B&H charges sales tax in NY & NJ only: – 10.5″ 64GB iPad Pro: $... Read more
Apple iMacs on sale for up to $130 off MSRP w...
B&H Photo has 21-inch and 27-inch iMacs in stock and on sale for up to $130 off MSRP including free shipping. B&H charges sales tax in NY & NJ only: – 27″ 3.8GHz iMac (MNED2LL/A): $2179 $... Read more
2017 3.5GHz 6-Core Mac Pro on sale for $2799,...
B&H Photo has the 2017 3.5GHz 6-Core Mac Pro (MD878LL/A) on sale today for $2799 including free shipping plus NY & NJ sales tax only . Their price is $200 off MSRP. Read more
12″ 1.2GHz Space Gray MacBook on sale for $11...
Amazon has the 2017 12″ 1.2GHz Space Gray Retina MacBook on sale for $100 off MSRP. Shipping is free: 12″ 1.2GHz Space Gray MacBook: $1199.99 $100 off MSRP Read more
Bare Bones Software Releases macOS High Sierr...
Bare Bones Software has announced the release and immediate availability of BBEdit 12.0, a significant upgrade to its professional strength text and code editor. BBEdit 12 introduces a new foundation... Read more
Yale Announces Availability of Apple HomeKit-...
Yale Locks & Hardware has announced that Apple HomeKit support for its Assure Lock family is available this month. The new Yale iM1 Network Module, which provides support for the Apple Home app... Read more

Jobs Board

*Apple* News Product Marketing Mgr., Publish...
Job Summary The Apple News Product Marketing Manager will work closely with a cross-functional group to assist in defining and marketing new features and services. Read more
Fraud Analyst, *Apple* Advertising Platform...
Job Summary Apple Ad Platforms has an opportunity to redefine advertising on mobile devices. Apple reaches hundreds of millions of iPhone, iPod touch, and iPad Read more
*Apple* Information Security - Security Data...
Job Summary This role is responsible for helping to strengthen Apple 's information security posture through the identification and curation of security event data. Read more
Lead *Apple* Solution Consultant - Apple In...
…develop a team of diverse partner employees focusing on excellence to deliver the Apple story. Even when you're not present, you will maintain a consistent influence Read more
watchOS Frameworks Engineering Manager, *App...
Job Summary Join the team that is shaping the future of software development for Apple Watch! Apple is looking for an exceptional software engineering leader to Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.