HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_Notifier.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: UT_Notifier.h UT library (C++)
7  *
8  * COMMENTS: Notifier that invokes registered functor callbacks whenever
9  * an event notification is triggered.
10  *
11  *
12  *
13  * HOW TO SET UP THE NOTIFIER AND THE CALLBACK:
14  *
15  * 1) decide what kind of event is passed from UT_NotifierImpl
16  * to the callback method. It can be an int, an enumerated
17  * type, or a class reference.
18  * For example,
19  * OP_Event &
20  *
21  * 2) in the observer class, write a method that handles events
22  * For example,
23  * void OP_SomeObserver::someHandler( OP_Event &event ) {}
24  *
25  * 3) in the observer class, declare the UT_NotifierList instance
26  * For example in .h,
27  * OP_SomeObserver
28  * {
29  * ...
30  * UT_NotifierList myNotifierList;
31  * ...
32  * };
33  *
34  * 4) in the emmitter class, instantiate the UT_NotifierImpl
35  * with <OP_Event &> as the type, and provide the accessor to it
36  * For example,
37  * OP_SomeEventEmmiter
38  * {
39  * UT_NotifierImpl<OP_Event&> &getNotifier()
40  * { return myNotifier; }
41  * ...
42  * private:
43  * UT_NotifierImpl<OP_Event &> myNotifier;
44  * };
45  *
46  * 5) in the observer class, create a functor that contains
47  * the callback method, and register the functor with notifier
48  * For example,
49  * void
50  * OP_SomeObserver::registerCallback( OP_SomeEventEmmiter *
51  * someEventEmitter )
52  * {
53  * UT_Functor1<void, OP_Event &>
54  * functor( this, &OP_SomeObserver::someHandler );
55  *
56  * someEventEmmiter->getEventNotifier().addObserver(
57  * myNotifierList, functor );
58  * }
59  *
60  * 6) whenever an event should be emitted, call notifiyObservers()
61  * on the notifier
62  * For example,
63  * void
64  * OP_SomeEventEmitter::someMethod()
65  * {
66  * ...
67  * OP_Event event( whatever, things, it, takes );
68  * myNotifier.notifyObservers( event );
69  * ...
70  * }
71  *
72  */
73 
74 #ifndef __UT_Notifier_h__
75 #define __UT_Notifier_h__
76 
77 #include "UT_API.h"
78 #include "UT_Array.h"
79 #include "UT_Functor.h"
80 #include "UT_Pair.h"
81 #include <SYS/SYS_Types.h>
82 
83 // declare UT_NotifierList for the use in UT_NotifierImpl
84 class UT_NotifierList;
85 
86 // a pure virtual base class to refer to by the notifier list
88 {
89 public:
90  virtual ~UT_Notifier() {};
91  virtual void removeObserver( UT_NotifierList & ) = 0;
92 };
93 
94 // define UT_NotifierImpl that handles the distribution of the notifications
95 template <typename EVENT_TYPE>
97 {
98 public:
100  virtual ~UT_NotifierImpl();
101 
102  // a definition of the callback functor
104 
105 
106  // ----------------------------------------------------------------------
107  // adds a callback functor to this notifier
108  // INPUTS:
109  // list - a list of notifiers the caller expressed interest in
110  // (which should not contain this notifier yet)
111  // callback - a functor invoked as a notification of an event
112  // OUTPUTS:
113  // list - the list is updated to include this notifier.
114  // If the list contained this notifier already, the
115  // callback is not registered (i.e., the old callback
116  // prevails)
117  // ----------------------------------------------------------------------
118  virtual void addObserver( UT_NotifierList &list, Callback &callback);
119 
120  // ----------------------------------------------------------------------
121  // removes a callback functor from this notifier
122  // INPUTS:
123  // list - a list of notifiers the caller expressed interest in
124  // (which should also contain this notifier)
125  // OUTPUTS:
126  // list - this notifier is removed from the list. If this notifier
127  // is not found in the list, no action is taken.
128  // ----------------------------------------------------------------------
129  virtual void removeObserver( UT_NotifierList &list );
130 
131  // ----------------------------------------------------------------------
132  // checks if this notifier has an observer registered
133  // INPUTS:
134  // list - a list based on which we check the observer registration
135  // RETURNS:
136  // true if the list was used to add an observer to this notifer, and
137  // the observer is still registered.
138  // false if this notifier has no callback functor was registered
139  // with the list.
140  // ----------------------------------------------------------------------
141  virtual bool hasObserver( const UT_NotifierList &list ) const;
142 
143  // ----------------------------------------------------------------------
144  // invokes all regisered functors using the event as argument
145  // INPUTS:
146  // event - an event passed to the functors
147  // NB:
148  // non-const because it needs to invoke a non-const functor, and if
149  // this method is const then only const functor is returned, which in
150  // turn tries to invoke operator() for which only non-const version
151  // is available
152  // ----------------------------------------------------------------------
153  virtual void notifyObservers( EVENT_TYPE event );
154 
155  /// Returns the amount of memory owned by this UT_NotifierImpl
156  int64 getMemoryUsage(bool inclusive) const
157  {
158  int64 mem = inclusive ? sizeof(*this) : 0;
159  mem += myObservers.getMemoryUsage(false);
160  for (exint i = 0; i < myObservers.entries(); ++i)
161  mem += myObservers(i).mySecond.getMemoryUsage(false);
162  return mem;
163  }
164 
165  // ----------------------------------------------------------------------
166  // return true if the notifier has observers
167  // INPUTS:
168  // none
169  // ----------------------------------------------------------------------
170  bool hasObservers() const;
171 
172 private:
173  // ----------------------------------------------------------------------
174  // finds the index to the observer list that contains the argument
175  // (i.e., the notifier list)
176  // INPUTS:
177  // list - a list based on which we check the observer registration
178  // RETURNS:
179  // index to the observer element containing "list"
180  // with the list.
181  // ----------------------------------------------------------------------
182  int getObserverIndex( const UT_NotifierList &list ) const;
183 
184  // ----------------------------------------------------------------------
185  // removes all observers
186  // ----------------------------------------------------------------------
187  void removeAllObservers();
188 
189  // ----------------------------------------------------------------------
190  // iterates through the whole list of observers and removes any entries
191  // that have NULL as their list member of the pair (i.e., entries that are
192  // marked for deletion)
193  // ----------------------------------------------------------------------
194  void pruneObservers();
195 
196 private:
197  // define a type that we are storing
198  typedef UT_Pair< UT_NotifierList*, Callback> ObserverPair;
199 
200  // list of registered callbacks to invoke during the distribution
201  // of notifications. The observers is an array of pairs. The pair
202  // contains a list pointer based on which we recognize observer,
203  // and the callback functor which is invoked as the notification.
204  UT_Array< ObserverPair > myObservers;
205 
206  // some state flags
207  bool myNotifyingFlag; // currently notifying observers
208  bool myPendingRemovalFlag; // list contains observers to remove
209 };
210 
211 // include the templated implementation
212 #if defined( WIN32 ) || defined( LINUX ) || defined( MBSD ) || defined(GAMEOS)
213  #include "UT_Notifier.C"
214 #endif
215 
216 #endif // __UT_Notifier_h__
virtual bool hasObserver(const UT_NotifierList &list) const
Definition: UT_Notifier.C:50
#define UT_API
Definition: UT_API.h:13
png_uint_32 i
Definition: png.h:2877
virtual void notifyObservers(EVENT_TYPE event)
Definition: UT_Notifier.C:140
struct _cl_event * event
Definition: glcorearb.h:2960
long long int64
Definition: SYS_Types.h:107
virtual ~UT_Notifier()
Definition: UT_Notifier.h:90
UT_Functor1< void, EVENT_TYPE > Callback
Definition: UT_Notifier.h:103
int64 exint
Definition: SYS_Types.h:116
virtual void removeObserver(UT_NotifierList &list)
Definition: UT_Notifier.C:81
virtual ~UT_NotifierImpl()
Definition: UT_Notifier.C:28
bool hasObservers() const
Definition: UT_Notifier.C:166
int64 getMemoryUsage(bool inclusive) const
Returns the amount of memory owned by this UT_NotifierImpl.
Definition: UT_Notifier.h:156
virtual void addObserver(UT_NotifierList &list, Callback &callback)
Definition: UT_Notifier.C:58