It's that time of the week again. No, it's not just time to go get drunk, but time for Friday Q&A! This week's topic, suggested by Christopher Lloyd of Cocotron (a really neat open source project that lets you write Objective-C/Cocoa code for non-Mac platforms like Windows), is NSNotificationQueue, a little-known, poorly-understood, but handy Foundation class.

Runloops
NSNotificationQueue works in close concert with NSRunLoop. If you haven't already, it might be a good idea to read my post from last week on NSRunLoop internals.

(No) Threading
Many people, upon confronted with NSNotificationQueue, immediately think that it allows posting notifications across threads. (Well, I did, anyway.) In fact, NSNotificationQueue is completely unrelated to threads! Like NSRunLoop, there exists a single NSNotificationQueue per thread, and that per-thread instance can't be used from other threasd.

So What Is It?
Simply put, the primary mission of NSNotificationQueue is to delay posting of a notification, and to allow coalescing of notifications.

Delayed Notifications
Sometimes you don't want to post a notification immediately. This is especially true if you want to coalesce multiple identical notifications; you can't do that unless you delay posting the first one. It can be useful for other scenarios as well, such as wanting to give calling code a chance to run before the notification's observers run. (In this respect, it's very similar to passing zero delay to performSelector:withObject:afterDelay: in order to have some code run at the next runloop cycle.)

NSNotificationQueue provides three posting styles for notifications:

    NSPostWhenIdle = 1,
    NSPostASAP = 2,
    NSPostNow = 3

NSPostNow is the easiest to understand. This has the same semantics as posting the notification directly to the NSNotificationCenter, in that the notification is posted immediately and observers are notified before control returns to the caller. The only reason to use this instead of NSNotificationCenter is because it can be used to coalesce previously enqueued notifications before posting.

NSPostASAP is much like a zero-delay timer. The notification is not posted immediately, but will be posted as soon as control returns to the runloop. The usage scenarios are much like for a zero-delay timer.

NSPostWhenIdle will wait until the runloop is idle, then post the notification. You can think of this as using a zero-delay timer with low priority. As long as the runloop has other work to do, the notification will not be posted. Once the runloop runs out of stuff to do, the notification will be posted. This is useful if you want to wait until your program has not only finished the currently executing code, but has nothing else to do. For example, imagine tracking mouse movement and performing an expensive update on the basis of that movement. Performing that update with every movement will make the program unresponsive, but you still want to update as often as possible within reason. Using NSPostWhenIdle will accomplish this. As long as more mouse movement events are pending, the notification will not be posted. If the user pauses for a moment, the runloop will clear out and the notification will be posted. If the user has a really fast computer, or the computation takes less time than expected, the runloop may have time to idle in between mouse moved events, and your update will then happen more frequently.

Coalescing
The real power of NSNotificationQueue is in coalescing. What does that mean?

When posting with NSPostASAP or NSPostWhenIdle, the notification is not posted immediately, but rather is queued. Coalescing means that if a notification is posted which matches one already in the queue, the two are merged, so that only a single notification is posted to observers.

This behavior can be really handy. Imagine a loop modifying a bunch of objects which posts notifications that cause other parts of the application to update their idea of the world. If they only need one notification at the end of all the modifications, coalescing will allow that other code to avoid a lot of needless computation that would occur if every modification caused a separate notification.

NSNotificationQueue provides three types of coalescing.

• NSNotificationNoCoalescing means that no coalescing is performed.
• NSNotificationCoalescingOnName means that coalescing is performed if two notifications share the same name.
• NSNotificationCoalescingOnSender means that coalescing is performed if two notifications share the same sender object.

With coalescing, the semantics of NSPostNow make more sense. By using NSPostNow with NSNotificationQueue, any matching enqueued notifications will be coalesced with the one being posted before it's posted, essentially clearing them out and posting the coalesced notification earlier than would have otherwise happened.

These coalescing flags can also be used to remove notifications from the queue without posting them, using the -dequeueNotificationsMatching:coalesceMask: method.

Examples
NSNotificationQueue is pretty straightforward to use. Rather than standard code using NSNotificationCenter, you more or less drop in NSNotificationQueue. As a concrete example, imagine you have an NSSlider set to be "continuous", so that it sends its action message every time the mouse is moved, even while it's down:

    - (IBAction)sliderMoved: (id)sender
    {
        [self updateWithNewSliderValue: [sender doubleValue]];

        NSNotification *note = [NSNotification notificationWithName: SliderDoneMovingNotification object: self];
        [[NSNotificationQueue defaultQueue] enqueueNotification: note postingStyle: NSPostASAP];

        note = [NSNotification notificationWithName: ExpensiveSliderUpdate object: self];
        NSArray *modes = [NSArray arrayWithObject: NSEventTrackingRunLoopMode];
        [[NSNotificationQueue defaultQueue] enqueueNotification: note
                                                   postingStyle: NSPostWhenIdle
                                                   coalesceMask: NSNotificationCoalescingOnName | NSNotificationCoalescingOnSender
                                                   forModes: modes];
    }

    - (void)sliderDoneMoving: (NSNotification *)note
    {
        NSNotification *note = [NSNotification notificationWithName: ExpensiveSliderUpdate object: self];
        [[NSNotificationQueue defaultQueue] dequeueNotificationsMatching: note
                                                            coalesceMask: NSNotificationCoalescingOnName | NSNotificationCoalescingOnSender];
    }

That's it for this week. Come back next week for another exciting edition. (A warning: I'm going to be making a long trip not long before next Friday, and so there's some possibility that I'll miss next week's edition. In that event, my instructions to you, the reader, are to panic as thoroughly as possible until the following Friday.)

As always, Friday Q&A is driven by reader suggestions. If you have an idea for a topic to cover here, please send it in!

Add your thoughts, post a comment:

Spam and off-topic posts will be deleted without notice. Culprits may be publicly humiliated at my sole discretion.