Run Loop Modes

A run loop mode is a collection of input sources and timers to be monitored and a collection of run loop observers to be notified. Each time you run your run loop, you specify (either explicitly or implicitly) a particular “mode” in which to run. During that pass of the run loop, only sources associated with that mode are monitored and allowed to deliver their events. (Similarly, only observers associated with that mode are notified of the run loop’s progress.) Sources associated with other modes hold on to any new events until subsequent passes through the loop in the appropriate mode.

In your code, you identify modes by name. Both Cocoa and Core Foundation define a default mode and several commonly used modes, along with strings for specifying those modes in your code. You can define custom modes by simply specifying a custom string for the mode name. Although the names you assign to custom modes are arbitrary, the contents of those modes are not. You must be sure to add one or more input sources, timers, or run-loop observers to any modes you create for them to be useful.

You use modes to filter out events from unwanted sources during a particular pass through your run loop. Most of the time, you will want to run your run loop in the system-defined “default” mode. A modal panel, however, might run in the “modal” mode. While in this mode, only sources relevant to the modal panel would deliver events to the thread. For secondary threads, you might use custom modes to prevent low-priority sources from delivering events during time-critical operations.

Table 3-1 lists the standard modes defined by Cocoa and Core Foundation along with a description of when you use that mode. The name column lists the actual constants you use to specify the mode in your code.

Input Sources

Input sources deliver events asynchronously to your threads. The source of the event depends on the type of the input source, which is generally one of two categories. Port-based input sources monitor your application’s Mach ports. Custom input sources monitor custom sources of events. As far as your run loop is concerned, it should not matter whether an input source is port-based or custom. The system typically implements input sources of both types that you can use as is. The only difference between the two sources is how they are signaled. Port-based sources are signaled automatically by the kernel, and custom sources must be signaled manually from another thread.

When you create an input source, you assign it to one or more modes of your run loop. Modes affect which input sources are monitored at any given moment. Most of the time, you run the run loop in the default mode, but you can specify custom modes too. If an input source is not in the currently monitored mode, any events it generates are held until the run loop runs in the correct mode.

The following sections describe some of the input sources.

Timer Sources

Timer sources deliver events synchronously to your threads at a preset time in the future. Timers are a way for a thread to notify itself to do something. For example, a search field could use a timer to initiate an automatic search once a certain amount of time has passed between successive key strokes from the user. The use of this delay time gives the user a chance to type as much of the desired search string as possible before beginning the search.

Although it generates time-based notifications, a timer is not a real-time mechanism. Like input sources, timers are associated with specific modes of your run loop. If a timer is not in the mode currently being monitored by the run loop, it does not fire until you run the run loop in one of the timer’s supported modes. Similarly, if a timer fires when the run loop is in the middle of executing a handler routine, the timer waits until the next time through the run loop to invoke its handler routine. If the run loop is not running at all, the timer never fires.

You can configure timers to generate events only once or repeatedly. A repeating timer reschedules itself automatically based on the scheduled firing time, not the actual firing time. For example, if a timer is scheduled to fire at a particular time and every 5 seconds after that, the scheduled firing time will always fall on the original 5 second time intervals, even if the actual firing time gets delayed. If the firing time is delayed so much that it misses one or more of the scheduled firing times, the timer is fired only once for the missed time period. After firing for the missed period, the timer is rescheduled for the next scheduled firing time.

For more information on configuring timer sources, see Configuring Timer Sources. For reference information, see NSTimer Class Reference or CFRunLoopTimer Reference.

Run Loop Observers

In contrast to sources, which fire when an appropriate asynchronous or synchronous event occurs, run loop observers fire at special locations during the execution of the run loop itself. You might use run loop observers to prepare your thread to process a given event or to prepare the thread before it goes to sleep. You can associate run loop observers with the following events in your run loop:

• The entrance to the run loop.

• When the run loop is about to process a timer.

• When the run loop is about to process an input source.

• When the run loop is about to go to sleep.

• When the run loop has woken up, but before it has processed the event that woke it up.

• The exit from the run loop.

You can add run loop observers to apps using Core Foundation. To create a run loop observer, you create a new instance of the CFRunLoopObserverRef opaque type. This type keeps track of your custom callback function and the activities in which it is interested.

Similar to timers, run-loop observers can be used once or repeatedly. A one-shot observer removes itself from the run loop after it fires, while a repeating observer remains attached. You specify whether an observer runs once or repeatedly when you create it.

For an example of how to create a run-loop observer, see Configuring the Run Loop. For reference information, see CFRunLoopObserver Reference.

The Run Loop Sequence of Events

Each time you run it, your thread’s run loop processes pending events and generates notifications for any attached observers. The order in which it does this is very specific and is as follows:

1. Notify observers that the run loop has been entered.

2. Notify observers that any ready timers are about to fire.

3. Notify observers that any input sources that are not port based are about to fire.

4. Fire any non-port-based input sources that are ready to fire.

5. If a port-based input source is ready and waiting to fire, process the event immediately. Go to step 9.

6. Notify observers that the thread is about to sleep.

7. Put the thread to sleep until one of the following events occurs:

   • An event arrives for a port-based input source.

   • A timer fires.

   • The timeout value set for the run loop expires.

   • The run loop is explicitly woken up.

8. Notify observers that the thread just woke up.

9. Process the pending event.

   • If a user-defined timer fired, process the timer event and restart the loop. Go to step 2.

   • If an input source fired, deliver the event.

   • If the run loop was explicitly woken up but has not yet timed out, restart the loop. Go to step 2.

10. Notify observers that the run loop has exited.

Because observer notifications for timer and input sources are delivered before those events actually occur, there may be a gap between the time of the notifications and the time of the actual events. If the timing between these events is critical, you can use the sleep and awake-from-sleep notifications to help you correlate the timing between the actual events.

Because timers and other periodic events are delivered when you run the run loop, circumventing that loop disrupts the delivery of those events. The typical example of this behavior occurs whenever you implement a mouse-tracking routine by entering a loop and repeatedly requesting events from the application. Because your code is grabbing events directly, rather than letting the application dispatch those events normally, active timers would be unable to fire until after your mouse-tracking routine exited and returned control to the application.

A run loop can be explicitly woken up using the run loop object. Other events may also cause the run loop to be woken up. For example, adding another non-port-based input source wakes up the run loop so that the input source can be processed immediately, rather than waiting until some other event occurs.

Getting a Run Loop Object

To get the run loop for the current thread, you use one of the following:

• In a Cocoa application, use the currentRunLoop class method of NSRunLoop to retrieve an NSRunLoop object.

• Use the CFRunLoopGetCurrent function.

Although they are not toll-free bridged types, you can get a CFRunLoopRef opaque type from an NSRunLoop object when needed. The NSRunLoop class defines a getCFRunLoop method that returns a CFRunLoopRef type that you can pass to Core Foundation routines. Because both objects refer to the same run loop, you can intermix calls to the NSRunLoop object and CFRunLoopRef opaque type as needed.

Configuring the Run Loop

Before you run a run loop on a secondary thread, you must add at least one input source or timer to it. If a run loop does not have any sources to monitor, it exits immediately when you try to run it. For examples of how to add sources to a run loop, see Configuring Run Loop Sources.

In addition to installing sources, you can also install run loop observers and use them to detect different execution stages of the run loop. To install a run loop observer, you create a CFRunLoopObserverRef opaque type and use the CFRunLoopAddObserver function to add it to your run loop. Run loop observers must be created using Core Foundation, even for Cocoa applications.

Listing 3-1 shows the main routine for a thread that attaches a run loop observer to its run loop. The purpose of the example is to show you how to create a run loop observer, so the code simply sets up a run loop observer to monitor all run loop activities. The basic handler routine (not shown) simply logs the run loop activity as it processes the timer requests.

Listing 3-1  Creating a run loop observer

- (void)threadMain

{

    // The application uses garbage collection, so no autorelease pool is needed.

    NSRunLoop* myRunLoop = [NSRunLoop currentRunLoop];

    // Create a run loop observer and attach it to the run loop.

    CFRunLoopObserverContext  context = {0, self, NULL, NULL, NULL};

    CFRunLoopObserverRef    observer = CFRunLoopObserverCreate(kCFAllocatorDefault,

            kCFRunLoopAllActivities, YES, 0, &myRunLoopObserver, &context);

    if (observer)

    {

        CFRunLoopRef    cfLoop = [myRunLoop getCFRunLoop];

        CFRunLoopAddObserver(cfLoop, observer, kCFRunLoopDefaultMode);

    }

    // Create and schedule the timer.

    [NSTimer scheduledTimerWithTimeInterval:0.1 target:self

                selector:@selector(doFireTimer:) userInfo:nil repeats:YES];

    NSInteger    loopCount = 10;

    do

    {

        // Run the run loop 10 times to let the timer fire.

        [myRunLoop runUntilDate:[NSDate dateWithTimeIntervalSinceNow:1]];

        loopCount--;

    }

    while (loopCount);

}

When configuring the run loop for a long-lived thread, it is better to add at least one input source to receive messages. Although you can enter the run loop with only a timer attached, once the timer fires, it is typically invalidated, which would then cause the run loop to exit. Attaching a repeating timer could keep the run loop running over a longer period of time, but would involve firing the timer periodically to wake your thread, which is effectively another form of polling. By contrast, an input source waits for an event to happen, keeping your thread asleep until it does.

Starting the Run Loop

Starting the run loop is necessary only for the secondary threads in your application. A run loop must have at least one input source or timer to monitor. If one is not attached, the run loop exits immediately.

There are several ways to start the run loop, including the following:

• Unconditionally

• With a set time limit

• In a particular mode

Entering your run loop unconditionally is the simplest option, but it is also the least desirable. Running your run loop unconditionally puts the thread into a permanent loop, which gives you very little control over the run loop itself. You can add and remove input sources and timers, but the only way to stop the run loop is to kill it. There is also no way to run the run loop in a custom mode.

Instead of running a run loop unconditionally, it is better to run the run loop with a timeout value. When you use a timeout value, the run loop runs until an event arrives or the allotted time expires. If an event arrives, that event is dispatched to a handler for processing and then the run loop exits. Your code can then restart the run loop to handle the next event. If the allotted time expires instead, you can simply restart the run loop or use the time to do any needed housekeeping.

In addition to a timeout value, you can also run your run loop using a specific mode. Modes and timeout values are not mutually exclusive and can both be used when starting a run loop. Modes limit the types of sources that deliver events to the run loop and are described in more detail in Run Loop Modes.

Listing 3-2 shows a skeleton version of a thread’s main entry routine. The key portion of this example shows the basic structure of a run loop. In essence, you add your input sources and timers to the run loop and then repeatedly call one of the routines to start the run loop. Each time the run loop routine returns, you check to see if any conditions have arisen that might warrant exiting the thread. The example uses the Core Foundation run loop routines so that it can check the return result and determine why the run loop exited. You could also use the methods of the NSRunLoop class to run the run loop in a similar manner if you are using Cocoa and do not need to check the return value. (For an example of a run loop that calls methods of the NSRunLoop class, see Listing 3-14.)

Listing 3-2  Running a run loop

- (void)skeletonThreadMain

{

    // Set up an autorelease pool here if not using garbage collection.

    BOOL done = NO;

    // Add your sources or timers to the run loop and do any other setup.

    do

    {

        // Start the run loop but return after each source is handled.

        SInt32    result = CFRunLoopRunInMode(kCFRunLoopDefaultMode, 10, YES);

        // If a source explicitly stopped the run loop, or if there are no

        // sources or timers, go ahead and exit.

        if ((result == kCFRunLoopRunStopped) || (result == kCFRunLoopRunFinished))

            done = YES;

        // Check for any other exit conditions here and set the

        // done variable as needed.

    }

    while (!done);

    // Clean up code here. Be sure to release any allocated autorelease pools.

}

It is possible to run a run loop recursively. In other words, you can call CFRunLoopRun, CFRunLoopRunInMode, or any of the NSRunLoop methods for starting the run loop from within the handler routine of an input source or timer. When doing so, you can use any mode you want to run the nested run loop, including the mode in use by the outer run loop.

Exiting the Run Loop

There are two ways to make a run loop exit before it has processed an event:

• Configure the run loop to run with a timeout value.

• Tell the run loop to stop.

Using a timeout value is certainly preferred, if you can manage it. Specifying a timeout value lets the run loop finish all of its normal processing, including delivering notifications to run loop observers, before exiting.

Stopping the run loop explicitly with the CFRunLoopStop function produces a result similar to a timeout. The run loop sends out any remaining run-loop notifications and then exits. The difference is that you can use this technique on run loops you started unconditionally.

Although removing a run loop’s input sources and timers may also cause the run loop to exit, this is not a reliable way to stop a run loop. Some system routines add input sources to a run loop to handle needed events. Because your code might not be aware of these input sources, it would be unable to remove them, which would prevent the run loop from exiting.

Thread Safety and Run Loop Objects

Thread safety varies depending on which API you are using to manipulate your run loop. The functions in Core Foundation are generally thread-safe and can be called from any thread. If you are performing operations that alter the configuration of the run loop, however, it is still good practice to do so from the thread that owns the run loop whenever possible.

The Cocoa NSRunLoop class is not as inherently thread safe as its Core Foundation counterpart. If you are using the NSRunLoop class to modify your run loop, you should do so only from the same thread that owns that run loop. Adding an input source or timer to a run loop belonging to a different thread could cause your code to crash or behave in an unexpected way.

Defining a Custom Input Source

Creating a custom input source involves defining the following:

• The information you want your input source to process.

• A scheduler routine to let interested clients know how to contact your input source.

• A handler routine to perform requests sent by any clients.

• A cancellation routine to invalidate your input source.

Because you create a custom input source to process custom information, the actual configuration is designed to be flexible. The scheduler, handler, and cancellation routines are the key routines you almost always need for your custom input source. Most of the rest of the input source behavior, however, happens outside of those handler routines. For example, it is up to you to define the mechanism for passing data to your input source and for communicating the presence of your input source to other threads.

Figure 3-2 shows a sample configuration of a custom input source. In this example, the application’s main thread maintains references to the input source, the custom command buffer for that input source, and the run loop on which the input source is installed. When the main thread has a task it wants to hand off to the worker thread, it posts a command to the command buffer along with any information needed by the worker thread to start the task. (Because both the main thread and the input source of the worker thread have access to the command buffer, that access must be synchronized.) Once the command is posted, the main thread signals the input source and wakes up the worker thread’s run loop. Upon receiving the wake up command, the run loop calls the handler for the input source, which processes the commands found in the command buffer.

The following sections explain the implementation of the custom input source from the preceding figure and show the key code you would need to implement.

@interface RunLoopSource : NSObject

{

    CFRunLoopSourceRef runLoopSource;

    NSMutableArray* commands;

}

- (id)init;

- (void)addToCurrentRunLoop;

- (void)invalidate;

// Handler method

- (void)sourceFired;

// Client interface for registering commands to process

- (void)addCommand:(NSInteger)command withData:(id)data;

- (void)fireAllCommandsOnRunLoop:(CFRunLoopRef)runloop;

@end

// These are the CFRunLoopSourceRef callback functions.

void RunLoopSourceScheduleRoutine (void *info, CFRunLoopRef rl, CFStringRef mode);

void RunLoopSourcePerformRoutine (void *info);

void RunLoopSourceCancelRoutine (void *info, CFRunLoopRef rl, CFStringRef mode);

// RunLoopContext is a container object used during registration of the input source.

@interface RunLoopContext : NSObject

{

    CFRunLoopRef        runLoop;

    RunLoopSource*        source;

}

@property (readonly) CFRunLoopRef runLoop;

@property (readonly) RunLoopSource* source;

- (id)initWithSource:(RunLoopSource*)src andLoop:(CFRunLoopRef)loop;

@end

void RunLoopSourceScheduleRoutine (void *info, CFRunLoopRef rl, CFStringRef mode)

{

    RunLoopSource* obj = (RunLoopSource*)info;

    AppDelegate*   del = [AppDelegate sharedAppDelegate];

    RunLoopContext* theContext = [[RunLoopContext alloc] initWithSource:obj andLoop:rl];

    [del performSelectorOnMainThread:@selector(registerSource:)

                                withObject:theContext waitUntilDone:NO];

}

void RunLoopSourcePerformRoutine (void *info)

{

    RunLoopSource*  obj = (RunLoopSource*)info;

    [obj sourceFired];

}

void RunLoopSourceCancelRoutine (void *info, CFRunLoopRef rl, CFStringRef mode)

{

    RunLoopSource* obj = (RunLoopSource*)info;

    AppDelegate* del = [AppDelegate sharedAppDelegate];

    RunLoopContext* theContext = [[RunLoopContext alloc] initWithSource:obj andLoop:rl];

    [del performSelectorOnMainThread:@selector(removeSource:)

                                withObject:theContext waitUntilDone:YES];

}

- (id)init

{

    CFRunLoopSourceContext    context = {0, self, NULL, NULL, NULL, NULL, NULL,

                                        &RunLoopSourceScheduleRoutine,

                                        RunLoopSourceCancelRoutine,

                                        RunLoopSourcePerformRoutine};

    runLoopSource = CFRunLoopSourceCreate(NULL, 0, &context);

    commands = [[NSMutableArray alloc] init];

    return self;

}

- (void)addToCurrentRunLoop

{

    CFRunLoopRef runLoop = CFRunLoopGetCurrent();

    CFRunLoopAddSource(runLoop, runLoopSource, kCFRunLoopDefaultMode);

}

- (void)registerSource:(RunLoopContext*)sourceInfo;

{

    [sourcesToPing addObject:sourceInfo];

}

- (void)removeSource:(RunLoopContext*)sourceInfo

{

    id    objToRemove = nil;

    for (RunLoopContext* context in sourcesToPing)

    {

        if ([context isEqual:sourceInfo])

        {

            objToRemove = context;

            break;

        }

    }

    if (objToRemove)

        [sourcesToPing removeObject:objToRemove];

}

- (void)fireCommandsOnRunLoop:(CFRunLoopRef)runloop

{

    CFRunLoopSourceSignal(runLoopSource);

    CFRunLoopWakeUp(runloop);

}

Configuring Timer Sources

To create a timer source, all you have to do is create a timer object and schedule it on your run loop. In Cocoa, you use the NSTimer class to create new timer objects, and in Core Foundation you use the CFRunLoopTimerRef opaque type. Internally, the NSTimer class is simply an extension of Core Foundation that provides some convenience features, like the ability to create and schedule a timer using the same method.

In Cocoa, you can create and schedule a timer all at once using either of these class methods:

• scheduledTimerWithTimeInterval:target:selector:userInfo:repeats:

• scheduledTimerWithTimeInterval:invocation:repeats:

These methods create the timer and add it to the current thread’s run loop in the default mode (NSDefaultRunLoopMode). You can also schedule a timer manually if you want by creating your NSTimer object and then adding it to the run loop using the addTimer:forMode: method of NSRunLoop. Both techniques do basically the same thing but give you different levels of control over the timer’s configuration. For example, if you create the timer and add it to the run loop manually, you can do so using a mode other than the default mode. Listing 3-10 shows how to create timers using both techniques. The first timer has an initial delay of 1 second but then fires regularly every 0.1 seconds after that. The second timer begins firing after an initial 0.2 second delay and then fires every 0.2 seconds after that.

Listing 3-10  Creating and scheduling timers using NSTimer

NSRunLoop* myRunLoop = [NSRunLoop currentRunLoop];

// Create and schedule the first timer.

NSDate* futureDate = [NSDate dateWithTimeIntervalSinceNow:1.0];

NSTimer* myTimer = [[NSTimer alloc] initWithFireDate:futureDate

                        interval:0.1

                        target:self

                        selector:@selector(myDoFireTimer1:)

                        userInfo:nil

                        repeats:YES];

[myRunLoop addTimer:myTimer forMode:NSDefaultRunLoopMode];

// Create and schedule the second timer.

[NSTimer scheduledTimerWithTimeInterval:0.2

                        target:self

                        selector:@selector(myDoFireTimer2:)

                        userInfo:nil

                        repeats:YES];

Listing 3-11 shows the code needed to configure a timer using Core Foundation functions. Although this example does not pass any user-defined information in the context structure, you could use this structure to pass around any custom data you needed for your timer. For more information about the contents of this structure, see its description in CFRunLoopTimer Reference.

Listing 3-11  Creating and scheduling a timer using Core Foundation

CFRunLoopRef runLoop = CFRunLoopGetCurrent();

CFRunLoopTimerContext context = {0, NULL, NULL, NULL, NULL};

CFRunLoopTimerRef timer = CFRunLoopTimerCreate(kCFAllocatorDefault, 0.1, 0.3, 0, 0,

                                        &myCFTimerCallback, &context);

CFRunLoopAddTimer(runLoop, timer, kCFRunLoopCommonModes);

Configuring a Port-Based Input Source

Both Cocoa and Core Foundation provide port-based objects for communicating between threads or between processes. The following sections show you how to set up port communication using several different types of ports.

- (void)launchThread

{

    NSPort* myPort = [NSMachPort port];

    if (myPort)

    {

        // This class handles incoming port messages.

        [myPort setDelegate:self];

        // Install the port as an input source on the current run loop.

        [[NSRunLoop currentRunLoop] addPort:myPort forMode:NSDefaultRunLoopMode];

        // Detach the thread. Let the worker release the port.

        [NSThread detachNewThreadSelector:@selector(LaunchThreadWithPort:)

               toTarget:[MyWorkerClass class] withObject:myPort];

    }

}

#define kCheckinMessage 100

// Handle responses from the worker thread.

- (void)handlePortMessage:(NSPortMessage *)portMessage

{

    unsigned int message = [portMessage msgid];

    NSPort* distantPort = nil;

    if (message == kCheckinMessage)

    {

        // Get the worker thread’s communications port.

        distantPort = [portMessage sendPort];

        // Retain and save the worker port for later use.

        [self storeDistantPort:distantPort];

    }

    else

    {

        // Handle other messages.

    }

}

+(void)LaunchThreadWithPort:(id)inData

{

    NSAutoreleasePool*  pool = [[NSAutoreleasePool alloc] init];

    // Set up the connection between this thread and the main thread.

    NSPort* distantPort = (NSPort*)inData;

    MyWorkerClass*  workerObj = [[self alloc] init];

    [workerObj sendCheckinMessage:distantPort];

    [distantPort release];

    // Let the run loop process things.

    do

    {

        [[NSRunLoop currentRunLoop] runMode:NSDefaultRunLoopMode

                            beforeDate:[NSDate distantFuture]];

    }

    while (![workerObj shouldExit]);

    [workerObj release];

    [pool release];

}

// Worker thread check-in method

- (void)sendCheckinMessage:(NSPort*)outPort

{

    // Retain and save the remote port for future use.

    [self setRemotePort:outPort];

    // Create and configure the worker thread port.

    NSPort* myPort = [NSMachPort port];

    [myPort setDelegate:self];

    [[NSRunLoop currentRunLoop] addPort:myPort forMode:NSDefaultRunLoopMode];

    // Create the check-in message.

    NSPortMessage* messageObj = [[NSPortMessage alloc] initWithSendPort:outPort

                                         receivePort:myPort components:nil];

    if (messageObj)

    {

        // Finish configuring the message and send it immediately.

        [messageObj setMsgId:setMsgid:kCheckinMessage];

        [messageObj sendBeforeDate:[NSDate date]];

    }

}

NSPort* localPort = [[NSMessagePort alloc] init];

// Configure the object and add it to the current run loop.

[localPort setDelegate:self];

[[NSRunLoop currentRunLoop] addPort:localPort forMode:NSDefaultRunLoopMode];

// Register the port using a specific name. The name must be unique.

NSString* localPortName = [NSString stringWithFormat:@"MyPortName"];

[[NSMessagePortNameServer sharedInstance] registerPort:localPort

                     name:localPortName];

#define kThreadStackSize        (8 *4096)

OSStatus MySpawnThread()

{

    // Create a local port for receiving responses.

    CFStringRef myPortName;

    CFMessagePortRef myPort;

    CFRunLoopSourceRef rlSource;

    CFMessagePortContext context = {0, NULL, NULL, NULL, NULL};

    Boolean shouldFreeInfo;

    // Create a string with the port name.

    myPortName = CFStringCreateWithFormat(NULL, NULL, CFSTR("com.myapp.MainThread"));

    // Create the port.

    myPort = CFMessagePortCreateLocal(NULL,

                myPortName,

                &MainThreadResponseHandler,

                &context,

                &shouldFreeInfo);

    if (myPort != NULL)

    {

        // The port was successfully created.

        // Now create a run loop source for it.

        rlSource = CFMessagePortCreateRunLoopSource(NULL, myPort, 0);

        if (rlSource)

        {

            // Add the source to the current run loop.

            CFRunLoopAddSource(CFRunLoopGetCurrent(), rlSource, kCFRunLoopDefaultMode);

            // Once installed, these can be freed.

            CFRelease(myPort);

            CFRelease(rlSource);

        }

    }

    // Create the thread and continue processing.

    MPTaskID        taskID;

    return(MPCreateTask(&ServerThreadEntryPoint,

                    (void*)myPortName,

                    kThreadStackSize,

                    NULL,

                    NULL,

                    NULL,

                    0,

                    &taskID));

}

#define kCheckinMessage 100

// Main thread port message handler

CFDataRef MainThreadResponseHandler(CFMessagePortRef local,

                    SInt32 msgid,

                    CFDataRef data,

                    void* info)

{

    if (msgid == kCheckinMessage)

    {

        CFMessagePortRef messagePort;

        CFStringRef threadPortName;

        CFIndex bufferLength = CFDataGetLength(data);

        UInt8* buffer = CFAllocatorAllocate(NULL, bufferLength, 0);

        CFDataGetBytes(data, CFRangeMake(0, bufferLength), buffer);

        threadPortName = CFStringCreateWithBytes (NULL, buffer, bufferLength, kCFStringEncodingASCII, FALSE);

        // You must obtain a remote message port by name.

        messagePort = CFMessagePortCreateRemote(NULL, (CFStringRef)threadPortName);

        if (messagePort)

        {

            // Retain and save the thread’s comm port for future reference.

            AddPortToListOfActiveThreads(messagePort);

            // Since the port is retained by the previous function, release

            // it here.

            CFRelease(messagePort);

        }

        // Clean up.

        CFRelease(threadPortName);

        CFAllocatorDeallocate(NULL, buffer);

    }

    else

    {

        // Process other messages.

    }

    return NULL;

}

OSStatus ServerThreadEntryPoint(void* param)

{

    // Create the remote port to the main thread.

    CFMessagePortRef mainThreadPort;

    CFStringRef portName = (CFStringRef)param;

    mainThreadPort = CFMessagePortCreateRemote(NULL, portName);

    // Free the string that was passed in param.

    CFRelease(portName);

    // Create a port for the worker thread.

    CFStringRef myPortName = CFStringCreateWithFormat(NULL, NULL, CFSTR("com.MyApp.Thread-%d"), MPCurrentTaskID());

    // Store the port in this thread’s context info for later reference.

    CFMessagePortContext context = {0, mainThreadPort, NULL, NULL, NULL};

    Boolean shouldFreeInfo;

    Boolean shouldAbort = TRUE;

    CFMessagePortRef myPort = CFMessagePortCreateLocal(NULL,

                myPortName,

                &ProcessClientRequest,

                &context,

                &shouldFreeInfo);

    if (shouldFreeInfo)

    {

        // Couldn't create a local port, so kill the thread.

        MPExit(0);

    }

    CFRunLoopSourceRef rlSource = CFMessagePortCreateRunLoopSource(NULL, myPort, 0);

    if (!rlSource)

    {

        // Couldn't create a local port, so kill the thread.

        MPExit(0);

    }

    // Add the source to the current run loop.

    CFRunLoopAddSource(CFRunLoopGetCurrent(), rlSource, kCFRunLoopDefaultMode);

    // Once installed, these can be freed.

    CFRelease(myPort);

    CFRelease(rlSource);

    // Package up the port name and send the check-in message.

    CFDataRef returnData = nil;

    CFDataRef outData;

    CFIndex stringLength = CFStringGetLength(myPortName);

    UInt8* buffer = CFAllocatorAllocate(NULL, stringLength, 0);

    CFStringGetBytes(myPortName,

                CFRangeMake(0,stringLength),

                kCFStringEncodingASCII,

                0,

                FALSE,

                buffer,

                stringLength,

                NULL);

    outData = CFDataCreate(NULL, buffer, stringLength);

    CFMessagePortSendRequest(mainThreadPort, kCheckinMessage, outData, 0.1, 0.0, NULL, NULL);

    // Clean up thread data structures.

    CFRelease(outData);

    CFAllocatorDeallocate(NULL, buffer);

    // Enter the run loop.

    CFRunLoopRun();

}