- Inherits from:
- NSObject
- Package:
- com.apple.yellow.foundation
NSNotificationQueue objects (or simply, notification queues) act as buffers for notification centers (instances of NSNotificationCenter). A notification queue maintains notifications (instances of NSNotification) generally in a First In First Out (FIFO) order. When a notification rises to the front of the queue, the queue posts it to the notification center, which in turn dispatches the notification to all objects registered as observers.
Every thread has a default notification queue, which is associated with the default notification center for the task. You can create your own notification queues and have multiple queues per center and thread.
NSNotificationQueue contributes two important features to the Foundation Kit's notification mechanism: the coalescing of notifications and asynchronous posting. Coalescing is a process that removes notifications in the queue that are similar to the notification just queued. If the new item is similar to a notification already queued, the new one isn't queued, and all similar notifications (except the first one in the queue) are removed. However, you should not depend on this particular coalescing behavior.
You indicate the criteria for similarity by specifying these constants, further described in "Constants" , in the third argument of enqueueNotificationWithCoalesceMaskForModes
You can OR the constants together to specify more than one.
With NSNotificationCenter's postNotification and its variants, you can post a notification immediately to a notification center. However, the invocation of the method is synchronous: Before the posting object can resume its thread of execution, it must wait until the notification center dispatches the notification to all observers and returns. With NSNotificationQueue's enqueueNotificationand enqueueNotificationWithCoalesceMaskForModes, however, you can post a notification asynchronously by putting it on the queue. These methods immediately return to the invoking object after putting the notification in the queue.
Posting to a notification queue can occur in one of three different styles, further described in "Constants" . The posting style is an argument to both enqueueNotificationand enqueueNotificationWithCoalesceMaskForModes:
Note: See "Enqueuing with Different Posting Styles" , below, for details on and examples of enqueuing notifications with the three postingStyle: constants. |
What is the difference between enqueuing notifications with PostNow
and
posting notifications (using NSNotificationCenter's postNotification... methods)?
Both post notifications immediately (but synchronously) to the notification
center. The difference is that enqueueNotification:... (with PostNow
as
the posting style) coalesces notifications in the queue before posting
while postNotification does not.
enqueueNotificationWithCoalesceMaskForModes also
allows you to control the posting of a notification based on the
run loop mode. For example, if you specify NSModalPanelRunLoopMode
,
the notification will not be posted unless the current run loop
is in NSModalPanelRunLoopMode
. See
the NSRunLoop class specification for more information on run loop
modes.
Any notification queued with the PostASAP
style
is posted to the notification center when the code executing in
the current run loop callout completes. Callouts can be Application
Kit event messages, file descriptor changes, timers, or other asynchronous
notifications. You typically use the PostASAP
posting
style for an expensive resource, such as the Display server. When
many clients draw on the window buffer during a callout, it's
expensive to flush the buffer to the Display server after every
draw operation. So in this case, each draw... method
enqueues some notification such as "FlushTheServer" with coalescing
on name and object specified, and a posting style of PostASAP.
As a result, only one of those notifications is dispatched at the
end of the current callout, and the window buffer is flushed only once.
A notification queued with the PostWhenIdle
style
is posted only when the run loop is in a wait state. In this state,
there's nothing in the run loop's input channels, be it timers
or other asynchronous notifications. A typical example of queuing
with the PostWhenIdle
style occurs
when the user types text, and the program displays the size of the
text in bytes somewhere. It would be very expensive (and not very
useful) to update the text field size after each character the user
types, especially if the user types quickly. In this case, the program
queues a notification, such as "ChangeTheDisplayedSize," with coalescing
turned on and a posting style of PostWhenIdle
after
each character typed. When the user stops typing, the single "ChangeTheDisplayedSize"
notification in the queue (due to coalescing) is posted when the
run loop is in a wait state, and the display is updated. Note that
a run loop that is about to exit (which occurs when all of the input
channels have expired) is not in a wait state and thus will not
post a notification.
A notification queued with PostNow
is
posted immediately after coalescing to the notification center. You
queue a notification with PostNow
(or
post one with NSNotificationCenter's postNotification) when you do not
require asynchronous calling behavior. For many programming situations, synchronous
behavior is not only allowable but desirable: You want the notification
center to return after dispatching so you can be sure that observing
objects have received the notification. Of course, you should use enqueueNotification... with PostNow
rather
than use postNotification when there are similar
notifications in the queue that you want to remove through coalescing.
These constants specify how notifications are coalesced. They're used in the third argument of enqueueNotificationWithCoalesceMaskForModes . You can OR them together to specify more than one.
Constant | Description |
NotificationNoCoalescing | Do not coalesce notifications in the queue. |
NotificationCoalescingOnName | Coalesce notifications with the same name. |
NotificationCoalescingOnSender | Coalesce notifications with the same object. |
These constants specify when notifications are posted. They're used in both enqueueNotificationand enqueueNotificationWithCoalesceMaskForModes:
Constant | Description |
PostASAP | The notification is posted at the end of the current notification callout or timer. |
PostWhenIdle | The notification is posted when the run loop is idle. |
PostNow | The notification is posted immediately after coalescing. |
- Constructors
- NSNotificationQueue
- Creating and Initializing Notification Queues
- defaultQueue
- Inserting and Removing Notifications From a Queue
- dequeueMatchingNotifications
- enqueueNotification
- enqueueNotificationWithCoalesceMaskForModes
public NSNotificationQueue()
public NSNotificationQueue(NSNotificationCenter notificationCenter)
public static NSNotificationQueue defaultQueue()
public void dequeueMatchingNotifications(
NSNotification notification,
int coalesceMask)
public void enqueueNotification(
NSNotification notification,
int postingStyle)
This method invokes enqueueNotificationWithCoalesceMaskForModes.
public void enqueueNotificationWithCoalesceMaskForModes(
NSNotification notification,
int postingStyle,
int coalesceMask,
NSArray modes)