---

NSNotificationQueue Class Reference

Overview

NSNotificationQueue objects (or simply notification queues) act as buffers for notification centers (instances of NSNotificationCenter). Whereas a notification center distributes notifications when posted, notifications placed into the queue can be delayed until the end of the current pass through the run loop or until the run loop is idle. Duplicate notifications can also be coalesced so that only one notification is sent although multiple notifications are posted. 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.

Tasks

Creating Notification Queues

• – initWithNotificationCenter:

Getting the Default Queue

• + defaultQueue

Managing Notifications

• – enqueueNotification:postingStyle:
• – enqueueNotification:postingStyle:coalesceMask:forModes:
• – dequeueNotificationsMatching:coalesceMask:

Class Methods

defaultQueue

Returns the default notification queue for the current thread.

+ (NSNotificationQueue *)defaultQueue

Return Value

Returns the default notification queue for the current thread. This notification queue uses the default notification center.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• Link Snoop

Declared In

NSNotificationQueue.h

Instance Methods

dequeueNotificationsMatching:coalesceMask:

Removes all notifications from the queue that match a provided notification using provided matching criteria.

- (void)dequeueNotificationsMatching:(NSNotification *)notification coalesceMask:(NSUInteger)coalesceMask

Parameters

notification

The notification used for matching notifications to remove from the notification queue.

coalesceMask

A mask indicating what criteria to use when matching attributes of notification to attributes of notifications in the queue. The mask is created by combining any of the constants NSNotificationNoCoalescing, NSNotificationCoalescingOnName, and NSNotificationCoalescingOnSender.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSNotificationQueue.h

enqueueNotification:postingStyle:

Adds a notification to the notification queue with a specified posting style.

- (void)enqueueNotification:(NSNotification *)notification postingStyle:(NSPostingStyle)postingStyle

Parameters

notification

The notification to add to the queue.

postingStyle

The posting style for the notification. The posting style indicates when the notification queue should post the notification to its notification center.

Discussion

Notifications added with this method are posted using the runloop mode NSDefaultRunLoopMode and coalescing criteria that will coalesce only notifications that match both the notification’s name and object.

This method invokes enqueueNotification:postingStyle:coalesceMask:forModes:.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• Link Snoop

Declared In

NSNotificationQueue.h

enqueueNotification:postingStyle:coalesceMask:forModes:

Adds a notification to the notification queue with a specified posting style, criteria for coalescing, and runloop mode.

- (void)enqueueNotification:(NSNotification *)notification postingStyle:(NSPostingStyle)postingStyle coalesceMask:(NSUInteger)coalesceMask forModes:(NSArray *)modes

Parameters

notification

The notification to add to the queue.

postingStyle

The posting style for the notification. The posting style indicates when the notification queue should post the notification to its notification center.

coalesceMask

A mask indicating what criteria to use when matching attributes of notification to attributes of notifications in the queue. The mask is created by combining any of the constants NSNotificationNoCoalescing, NSNotificationCoalescingOnName, and NSNotificationCoalescingOnSender.

modes

The list of modes the notification may be posted in. The notification queue will only post the notification to its notification center if the run loops is in one of the modes provided in the array. May be nil, in which case it defaults to NSDefaultRunLoopMode.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSNotificationQueue.h

initWithNotificationCenter:

Initializes and returns a notification queue for the specified notification center.

- (id)initWithNotificationCenter:(NSNotificationCenter *)notificationCenter

Parameters

notificationCenter

The notification center used by the new notification queue.

Return Value

The newly initialized notification queue.

Discussion

This is the designated initializer for the NSNotificationQueue class.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSNotificationQueue.h

Constants

NSNotificationCoalescing

These constants specify how notifications are coalesced.

typedef enum {
   NSNotificationNoCoalescing = 0,
   NSNotificationCoalescingOnName = 1,
   NSNotificationCoalescingOnSender = 2
} NSNotificationCoalescing;

Constants

NSNotificationNoCoalescing

Do not coalesce notifications in the queue.

Available in Mac OS X v10.0 and later.

Declared in NSNotificationQueue.h.

NSNotificationCoalescingOnName

Coalesce notifications with the same name.

Available in Mac OS X v10.0 and later.

Declared in NSNotificationQueue.h.

NSNotificationCoalescingOnSender

Coalesce notifications with the same object.

Available in Mac OS X v10.0 and later.

Declared in NSNotificationQueue.h.

Discussion

These constants are used in the third argument of enqueueNotification:postingStyle:coalesceMask:forModes:. You can OR them together to specify more than one.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSNotificationQueue.h

NSPostingStyle

These constants specify when notifications are posted.

typedef enum {
   NSPostWhenIdle = 1,
   NSPostASAP = 2,
   NSPostNow = 3
} NSPostingStyle;

Constants

NSPostASAP

The notification is posted at the end of the current notification callout or timer.

Available in Mac OS X v10.0 and later.

Declared in NSNotificationQueue.h.

NSPostWhenIdle

The notification is posted when the run loop is idle.

Available in Mac OS X v10.0 and later.

Declared in NSNotificationQueue.h.

NSPostNow

The notification is posted immediately after coalescing.

Available in Mac OS X v10.0 and later.

Declared in NSNotificationQueue.h.

Discussion

These constants are used in both enqueueNotification:postingStyle: and enqueueNotification:postingStyle:coalesceMask:forModes:.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSNotificationQueue.h

---