EOObserver

Authors

Mirko Viviani (mirko.viviani@gmail.com)
David Ayers (ayers@fsfe.org)

Version: 25326

Date: 2007-07-12 08:39:22 +0200 (Don, 12 Jul 2007)

Contents -

Software documentation for the EODelayedObserver class
Software documentation for the EODelayedObserverQueue class
Software documentation for the EOObserverCenter class
Software documentation for the EOObserverProxy class
Software documentation for the NSObject(EOObserver) category
Software documentation for the EOObserving protocol
EOObserver types

Software documentation for the EODelayedObserver class

EODelayedObserver : NSObject

Declared in:

EOControl/EOObserver.h

Conforms to:

EOObserving

Description forthcoming.

Instance Variables

Method summary

discardPendingNotification

- (void) discardPendingNotification;

Discards all pending notifications of the receiver by dequeuing the receiver from the observer queue returned by -observerQueue . Subclasses should invoke this method in thier dealloc implementations.

objectWillChange:

- (void) objectWillChange: (id)subject;

<EOObserving> implementation which enqueues the receiver in the queue returned by observerQueue.

observerQueue

- (EODelayedObserverQueue*) observerQueue;

Returns the receivers observer queue. EODelayedObserver returns [EODelayedObserverQueue +defaultObserverQueue] . Subclasses can override this method to return an applicable queue.

priority

- (EOObserverPriority) priority;

Returns the EOObserverPriority of the receiver. EODelayedObserver returns EOObserverPriorityThird by default. Subclasses can override this method to return the corresponding priority.

subjectChanged

- (void) subjectChanged;

Invoked by [EODelayedObserverQueue -notifyObserversUpToPriority:] or [EODelayedObserverQueue -enqueueObserver:] . Overridden by subclasses to process the delayed change notification. EODelayesObserver does nothing.

Instance Variables for EODelayedObserver Class

_next

@public EODelayedObserver* _next;

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

Software documentation for the EODelayedObserverQueue class

EODelayedObserverQueue : NSObject

Declared in:

EOControl/EOObserver.h

EODelayedObserverQueue manages the delayed observer notifications for EODelayedObserver that register with it. A delayed observer may only register itself with one queue and a fixed priority. Upon [-notifyObserversUpToPriority:] all enqueued observers are sent [EODelayedObserver -subjectChanged] according to the EOObserverPriority of the observer. The first time an observer is enqueued with [-enqueueObserver:] (with a priority other than EOObserverPriorityImmediate) the queue registers itself with the NSRunLoop currentRunLoop with EOFlushDelayedObserverRunLoopOrdering to invoke [-notifyObserversUpToPriority:] with EOObserverPrioritySixth. In general this mechanism is used by EOAssociation subclasses and in part EODisplayGroup or even EOEditingContext .

Instance Variables

Method summary

defaultObserverQueue

+ (EODelayedObserverQueue*) defaultObserverQueue;

Returns the default queue.

dequeueObserver:

- (void) dequeueObserver: (EODelayedObserver*)observer;

Unregisters the observer from the receiver.

enqueueObserver:

- (void) enqueueObserver: (EODelayedObserver*)observer;

Registers the observer with the receiver so that it will dispatch [EODelayedObserver -subjectChanged] either immediately, if the observers priority is EOObserverPriorityImmediate, or for the next invocation of -notifyObserversUpToPriority: . If this method is invoked during the processing of -notifyObserversUpToPriority: , then the dispatch will be enqueue for the current processing.

Upon the first invocation within a run loop, this method registers a callback method to have [-notifyObserversUpToPriority:] invoked with EOObserverPrioritySixth with the NSRunLoop currentRunLoop with EOFlushDelayedObserverRunLoopOrdering and the receivers run loop modes.

The observer is not retained and should be removed from the receiver with [-dequeueObserver:] during the EODelayedObservers NSObject dealloc method.

notifyObserversUpToPriority:

- (void) notifyObserversUpToPriority: (EOObserverPriority)priority;

Dispatches registered observer notifications by sending [EODelayedObserver -subjectChanged] to all registered observers of the receiver. During the processing new enqueObserver: methods will be honored. It is up toe the callers to ensure no loops result.

This method is invoked automatically with EOObserverPrioritySixth during each run loop after an invocation of -enqueueObserver: .

Note that unlike the reference implementation, we dequeue the observer after dispatching [EODelayedObserver -subjectChanged] .

runLoopModes

- (NSArray*) runLoopModes;

Returns the run loop modes the receiver uses when registering for [-notifyObserversUpToPriority:] during -enqueueObserver: . (see NSRunLoop).

setRunLoopModes:

- (void) setRunLoopModes: (NSArray*)modes;

Sets the run loop modes the receiver uses when registering for [-notifyObserversUpToPriority:] during -enqueueObserver: . (see NSRunLoop).

Instance Variables for EODelayedObserverQueue Class

_haveEntryInNotificationQueue

@protected BOOL _haveEntryInNotificationQueue;

_highestNonEmptyQueue

@protected unsigned int _highestNonEmptyQueue;

_modes

@protected NSArray* _modes;

_queue

@protected EODelayedObserver* _queue;

Software documentation for the EOObserverCenter class

EOObserverCenter : NSObject

Declared in:

EOControl/EOObserver.h

This is the central coordinating class of the change tracking system of EOControl. It manages the observers <EOObserving> and the objects to be observed. No instances of this class should be needed or created. All methods for coordinating the tracking mechanism are class methods.

Observers must implement the <EOObserving> protocol, in particular [<EOObserving>-objectWillChange:] while the observed objects must invoke [NSObject -willChange] . Invoke [+addObserver:forObject:] to register an observer for a particular object. That will setup for [<EOObserving>-objectWillChange:] to be invoked on the observer each time [NSObject -willChange] gets called. To remove an observer invoke +removeObserver:forObject: . For observers who wish to be notified for every change the methods [+addOmniscientObserver:] and [+removeOmniscientObserver:] can be used.

Method summary

addObserver: forObject:

+ (void) addObserver: (id<EOObserving>)observer forObject: (id)object;

Adds the observer to be notified with a [<EOObserving>-objectWillChange:] on the first of consecutive [NSObject -willChange] methods invoked on the object.

This does not retain the object. It is the observers responsibility to unregister the object with [+removeObserver:forObject:] before the object ceases to exist. The observer is also not retained. It is the observers responsibility to unregister before it ceases to exist.

Both observer and object equality are considered equal through pointer equality, so an observer observing multiple objects considered isEqual: will recieve multiple observer notifications, objects considered isEqual: may contain different sets of observers, and an object can have multiple observers considered isEqual:.

addOmniscientObserver:

+ (void) addOmniscientObserver: (id<EOObserving>)observer;

Adds observer as an omniscient observer to receive [<EOObserving>-objectWillChange:] for all objects and nil.

enableObserverNotification

+ (void) enableObserverNotification;

Decreases the notification suppression count. This should be called to pair up [+suppressObserverNotification] invocations. When they all have been paired up [+notifyObserversObjectWillChange:] will continue to dispatch [<EOObserving>-objectWillChange:] methods again. If this is invoked when the [+observerNotificationSuppressCount] is 0, this method raises an NSInternalInconsistencyException.

notifyObserversObjectWillChange:

+ (void) notifyObserversObjectWillChange: (id)object;

This method is invoked from [NSObject -willChange] to dispatch [<EOObserving>-objectWillChange:] to all observers registered to observe object. This method records the last object it was invoked with so that subsequent invocations with the same object get ignored. Invoke this method with nil as the object to insure that the new changes will be forwarded to the observer. The observer notification can be suppressed with invocations of [+suppressObserverNotification] which must be paired up with invocations of [+enableObserverNotification] before they are dispatched again.

observerForObject: ofClass:

+ (id) observerForObject: (id)object ofClass: (Class)targetClass;

Returns the first observer of the object that matches [-isKindOfClass:] of the targetClass.

observerNotificationSuppressCount

+ (unsigned) observerNotificationSuppressCount;

Returns the current observer notification suppress count.

observersForObject:

+ (NSArray*) observersForObject: (id)object;

Returns an array of observers that have been registered of object. Note that this class is considered 'final' and that for efficiency the observers are accessed directly internally, thus overriding this method could lead to unexpected results. In other words, if you must subclass then you should override all methods that access the internal map if this method is overridden to use a different store.

removeObserver: forObject:

+ (void) removeObserver: (id<EOObserving>)observer forObject: (id)object;

Removes the observer from being notified on [NSObject -willChange] invocations of object.

removeOmniscientObserver:

+ (void) removeOmniscientObserver: (id<EOObserving>)observer;

Removes observer as an omniscient observer.

suppressObserverNotification

+ (void) suppressObserverNotification;

Increases the notification suppression count. When the count is non zero [+notifyObserversObjectWillChange:] invocations do nothing. Call [+enableObserverNotification] a matching amount of times to enable the dispatch of those notifications again.

Software documentation for the EOObserverProxy class

EOObserverProxy : EODelayedObserver

Declared in:

EOControl/EOObserver.h

This is a convenience class which is initialized with a target, an action method and a priority, to have the action method invoked on the target when the subjectChanged method is invoked by the EODelayedObserverQueue.

Instance Variables

Method summary

-initWithTarget:action:priority:

initWithTarget: action: priority:

- (id) initWithTarget: (id)target action: (SEL)action priority: (EOObserverPriority)priority;

Initializes the receiver to dispatch action to target upon processing -subjectChanged . The receiver uses priority for the EODelayedObserverQueue . Target is not retained.

Instance Variables for EOObserverProxy Class

_action

@protected SEL _action;

_priority

@protected EOObserverPriority _priority;

_target

@protected id _target;

Software documentation for the NSObject(EOObserver) category

NSObject(EOObserver)

Declared in:

EOControl/EOObserver.h

Description forthcoming.

Method summary

-willChange

willChange

- (void) willChange;

This is the hook to allow observers to be notified that the state of the receiver is about to change. The method should be called in all mutating accessor methods before the state of the receiver changes. This method invokes [EOObserverCenter +notifyObserversObjectWillChange:] with the receiver. It is responsible for invoking [<EOObserving>-objectWillChange:] for all corresponding observers.

Software documentation for the EOObserving protocol

EOObserving

Declared in:

EOControl/EOObserver.h

Conforms to:

NSObject

Description forthcoming.

Method summary

-objectWillChange:

objectWillChange:

- (void) objectWillChange: (id)subject;

Description forthcoming.

EOObserver types

EOObserverPriority

typedef enum ... EOObserverPriority;

Description forthcoming.