This is NSNotificationQueue.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s10 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSNotificationQueue
pard s24 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSObject
fs20
fs28 s14 f0 b fs24 Conforms To:tab b0 fs28 f1 NSObject (NSObject)
fs20
fs28 s15 f0 b fs24 Declared In:tab b0 fs28 f1 Foundation/NSNotificationQueue.h
fs20
fs28 pard s38 li100 fi0 ri1007 ql f0 b fs28 fs20
fs28 Class Description
fs14
fs28 pard s2 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 NSNotificationQueue objects (or simply, i notification queuesi0 ) act as buffers for notifications centers (instances of NSNotificationCenter). A notification queue maintains notifications (instances of NSNotification) generally in a FIFO order (First In First Out). When a notification rises to the 'aatop'ba of the queue, the queue posts it to the notification center, which in turn dispatches the notification to all objects registered as observers.
fs16
fs28 NSNotificationQueue contributes two important features to OpenStep'27s notification mechanism: asynchronous posting and the coalescing of notifications. With NSNotificationCenter'27s b postNotification:b0 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'27s b enqueueNotification:postingStyle: b0 andb enqueueNotification:postingStyle:coalesceMask:forModesb0 :, 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.
fs16
fs28 Posting to a notification queue can occur in one of three different styles. The posting style is an argument to both b enqueueNotification:...b0 methods:
fs16
fs28 pard s4 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab b NSPostWhenIdleb0 . The notification is posted when the run loop is idle.
fs16
fs28 'b7tab b NSPostASAPb0 . The notification is posted as soon as possible.
fs16
fs28 'b7tab b NSPostNowb0 . The notification is posted immediately to the notification center.
fs16
fs28 pard s33 li477 fi0 ri1007 ql f0 b fs24 Note: b0 fs28 f1 See 'aaEnqueuing with the Different Posting Styles,'ba below, for details on and examples of enqueuing notifications with the three b postingStyle:b0 constants.
fs14
fs28 pard s2 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 fs2
fs28 What is the difference between enqueuing notifications with b NSPostNowb0 and posting notifications (b postNotification:b0 )? Both post notifications immediately (but synchronously) to the notification center. The difference is that b enqueueNotification:...b0 (with b NSPostNowb0 as posting style) coalesces notifications in the queue before posting while b postNotification:b0 does not.
fs16
fs28 Coalescing is a process that removes notifications in the queue that are similar to the notification just enqueued (or posted, if posting style is b NSPostNowb0 . The notification queue scans the notifications in the queue for those with attributes matching the new notification and removes them, except for the notification that is topmost in the queue (closest to being posted). You indicate the criteria for similarity by specifying the NSNotificationCoalescing constants in the third argument of b enqueueNotification:postingStyle:coalesceMask:forModesb0 : (OR them in if multiple):
fs16
fs28 pard s4 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab b NSNotificationNoCoalescingb0 . Do not coalesce notifications in the queue.
fs16
fs28 'b7tab b NSNotificationCoalescingOnNameb0 . Coalesce notifications with the same name.
fs16
fs28 'b7tab b NSNotificationCoalescingOnSenderb0 . Coalesce notifications with the same sender.
fs16
fs28 pard s2 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 Every task has a default notification queue, which is associated with the task'27s default notification center. You can create your own notification queues, and have multiple queues per center and task; but you can have only one notification center per task. NSNotificationQueue is a public, concrete class; instances of it are mutable.
fs16
fs28 pard s37 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Enqueuing with the Different Posting Styles
pard s2 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 Any notification enqueued with the b NSPostASAPb0 posting 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 another asynchronous notification. You'27d typically use the b NSPostASAPb0 posting style for an expensive resource, like the Display PostScript server. When many clients draw on the window buffer during a callout, it'27s expensive to flush the buffer to the Display PostScript server after every draw operation. So in this case, each b draw...b0 method enqueues some notification such as 'aaFlushTheServer'bab b0 with coalescing on name and sender specified, and a posting style of b NSPostASAPb0 . 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.
fs16
fs28 A notification enqueued with the b NSPostIdleb0 posting style is posted only when the run loop is in a wait state. In this state, there is nothing in the run loop'27s input channels, be it timers or other asynchronous notifications. A typical example of enqueuing with the b NSPostIdleb0 posting 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 displayed size after each character the user types, especially if the user types fast. In this case, the program enqueues a notification after each character typed such as 'aaChangeTheDisplayedSize'ba with coalescing turned on and a posting style of b NSPostWhenIdleb0 . When the user stops typing, the single 'aaChangeTheDisplayedSize'ba notification in the queue (due to coalescing) is posted when the run loop is in a wait state and the display is updated.
fs16
fs28 A notification enqueued with b NSPostNowb0 is posted immediately to the notification center. You enqueue a notification with b NSPostNowb0 (or post one with NSNotificationCenter'27s b postNotification:b0 ) 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 enqueue with b NSPostNowb0 rather than use b postNotification:b0 when there are similar notifications in the queue that you want to remove through coalescing.
fs16
fs28 pard s38 li100 fi0 ri1007 ql f0 b fs24
fs28 Creating Notification Queues
fs14
fs28 pard s16 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSNotificationQueue *)b defaultQueueb0 tab Returns the default NSNotificationQueue object for the current task. This object always uses the default notification-center object for the same task.
fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b inittab b0 Initializes and returns an NSNotificationQueue object that uses the default notification-center object.
fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b initWithNotificationCenter:b0 (NSNotificationCenter *)i notificationCenter
s18 li7030 fi-6553 fi-5796 i0 tab Initializes and returns an NSNotificationQueue object that uses the notification-center object specified in i notificationCenteri0 .
pard s38 li100 fi0 ri1007 ql f0 b fs48
fs28 Inserting and Removing Notifications From a Queue
fs14
fs28 pard s16 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b dequeueNotificationsMatching:b0 (NSNotification *)i notification
s18 li7030 fi-6553 fi-5796 i0 b coalesceMask:b0 (unsigned int)i coalesceMasktab i0 Removes all notifications from the queue that match the i notificationi0 '27s attributes as specified by i coalesceMaski0 . The mask (set through NSNotificationCoalescing constants) can specify notification name, notification sender, or both name and sender.
s16 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b enqueueNotification:b0 (NSNotification *)i notification
s18 li7030 fi-6553 fi-5796 i0 b postingStyle:b0 (NSPostingStyle)i postingStyletab i0 Puts a i notificationi0 in the queue that the queue will post to thei i0 notification center at the time indicated by i postingStyle. i0 The notification queue posts in all runloop modes, and it coalesces only notifications in the queue that match both the name and sender of i notification
s16 li7029 fi-5794 fi-6552 i0 fs16
fs28 fi-6552 {f3 -} (void)b enqueueNotification:b0 (NSNotification *)i notification
s18 li7030 fi-6553 fi-5796 i0 b postingStyle:b0 (NSPostingStyle)i postingStyletab i0 Puts a i notificationi0 in the queue that the queue will post to
b coalesceMask:b0 (unsigned int)i coalesceMasktab i0 tab the notification center at the time indicated by
b forModes:b0 (NSArray *)i modestab i0 tab i postingStyle,i0 but only if the runloop is in a mode identified by one of the string objects in the i modesi0 array. The notification queue coalesces related notifications in the queue as specified by i coalesceMaski0 . If i modesi0 is b nilb0 , all runloop modes are valid for posting.
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.