Mac Developer Library

Developer

Foundation Framework Reference NSNotificationQueue Class Reference

Options
Deployment Target:

On This Page
Language:

NSNotificationQueue

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.

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.
  • Initializes and returns a notification queue for the specified notification center.

    Declaration

    Swift

    init(notificationCenter notificationCenter: NSNotificationCenter)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the default notification queue for the current thread.

    Declaration

    Swift

    class func defaultQueue() -> NSNotificationQueue

    Objective-C

    + (NSNotificationQueue *)defaultQueue

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func enqueueNotification(_ notification: NSNotification, postingStyle postingStyle: NSPostingStyle)

    Objective-C

    - (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:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func enqueueNotification(_ notification: NSNotification, postingStyle postingStyle: NSPostingStyle, coalesceMask coalesceMask: Int, forModes modes: [AnyObject]?)

    Objective-C

    - (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 loop is in one of the modes provided in the array. May be nil, in which case it defaults to NSDefaultRunLoopMode.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func dequeueNotificationsMatching(_ notification: NSNotification, coalesceMask coalesceMask: Int)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

Data Types

  • These constants specify how notifications are coalesced.

    Declaration

    Swift

    enum NSNotificationCoalescing : UInt { case NoCoalescing case CoalescingOnName case CoalescingOnSender }

    Objective-C

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

    Constants

    • NoCoalescing

      NSNotificationNoCoalescing

      Do not coalesce notifications in the queue.

      Available in OS X v10.0 and later.

    • CoalescingOnName

      NSNotificationCoalescingOnName

      Coalesce notifications with the same name.

      Available in OS X v10.0 and later.

    • CoalescingOnSender

      NSNotificationCoalescingOnSender

      Coalesce notifications with the same object.

      Available in OS X v10.0 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • These constants specify when notifications are posted.

    Declaration

    Swift

    enum NSPostingStyle : UInt { case PostWhenIdle case PostASAP case PostNow }

    Objective-C

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

    Constants

    • PostASAP

      NSPostASAP

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

      Available in OS X v10.0 and later.

    • PostWhenIdle

      NSPostWhenIdle

      The notification is posted when the run loop is idle.

      Available in OS X v10.0 and later.

    • PostNow

      NSPostNow

      The notification is posted immediately after coalescing.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.