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 <SYS/SYS_Types.h>
81 
82 #include <utility>
83 
84 // declare UT_NotifierList for the use in UT_NotifierImpl
85 class UT_NotifierList;
86 
87 // a pure virtual base class to refer to by the notifier list
89 {
90 public:
91  virtual ~UT_Notifier() {};
92  virtual void removeObserver( UT_NotifierList & ) = 0;
93 };
94 
95 // define UT_NotifierImpl that handles the distribution of the notifications
96 template <typename EVENT_TYPE>
98 {
99 public:
100  UT_NotifierImpl();
101  ~UT_NotifierImpl() override;
102 
103  // a definition of the callback functor
105 
106 
107  // ----------------------------------------------------------------------
108  // adds a callback functor to this notifier
109  // INPUTS:
110  // list - a list of notifiers the caller expressed interest in
111  // (which should not contain this notifier yet)
112  // callback - a functor invoked as a notification of an event
113  // OUTPUTS:
114  // list - the list is updated to include this notifier.
115  // If the list contained this notifier already, the
116  // callback is not registered (i.e., the old callback
117  // prevails)
118  // ----------------------------------------------------------------------
119  virtual void addObserver( UT_NotifierList &list, Callback &callback);
120 
121  // ----------------------------------------------------------------------
122  // removes a callback functor from this notifier
123  // INPUTS:
124  // list - a list of notifiers the caller expressed interest in
125  // (which should also contain this notifier)
126  // OUTPUTS:
127  // list - this notifier is removed from the list. If this notifier
128  // is not found in the list, no action is taken.
129  // ----------------------------------------------------------------------
130  void removeObserver( UT_NotifierList &list ) override;
131 
132  // ----------------------------------------------------------------------
133  // checks if this notifier has an observer registered
134  // INPUTS:
135  // list - a list based on which we check the observer registration
136  // RETURNS:
137  // true if the list was used to add an observer to this notifer, and
138  // the observer is still registered.
139  // false if this notifier has no callback functor was registered
140  // with the list.
141  // ----------------------------------------------------------------------
142  virtual bool hasObserver( const UT_NotifierList &list ) const;
143 
144  // ----------------------------------------------------------------------
145  // invokes all regisered functors using the event as argument
146  // INPUTS:
147  // event - an event passed to the functors
148  // NB:
149  // non-const because it needs to invoke a non-const functor, and if
150  // this method is const then only const functor is returned, which in
151  // turn tries to invoke operator() for which only non-const version
152  // is available
153  // ----------------------------------------------------------------------
154  virtual void notifyObservers( EVENT_TYPE event );
155 
156  /// Returns the amount of memory owned by this UT_NotifierImpl
157  int64 getMemoryUsage(bool inclusive) const
158  {
159  int64 mem = inclusive ? sizeof(*this) : 0;
160  mem += myObservers.getMemoryUsage(false);
161  for (exint i = 0; i < myObservers.entries(); ++i)
162  mem += myObservers(i).second.getMemoryUsage(false);
163  return mem;
164  }
165 
166  // ----------------------------------------------------------------------
167  // return true if the notifier has observers
168  // INPUTS:
169  // none
170  // ----------------------------------------------------------------------
171  bool hasObservers() const;
172 
173 private:
174  // ----------------------------------------------------------------------
175  // finds the index to the observer list that contains the argument
176  // (i.e., the notifier list)
177  // INPUTS:
178  // list - a list based on which we check the observer registration
179  // RETURNS:
180  // index to the observer element containing "list"
181  // with the list.
182  // ----------------------------------------------------------------------
183  int getObserverIndex( const UT_NotifierList &list ) const;
184 
185  // ----------------------------------------------------------------------
186  // removes all observers
187  // ----------------------------------------------------------------------
188  void removeAllObservers();
189 
190  // ----------------------------------------------------------------------
191  // iterates through the whole list of observers and removes any entries
192  // that have NULL as their list member of the pair (i.e., entries that are
193  // marked for deletion)
194  // ----------------------------------------------------------------------
195  void pruneObservers();
196 
197 private:
198  // define a type that we are storing
199  typedef std::pair< UT_NotifierList*, Callback> ObserverPair;
200 
201  // list of registered callbacks to invoke during the distribution
202  // of notifications. The observers is an array of pairs. The pair
203  // contains a list pointer based on which we recognize observer,
204  // and the callback functor which is invoked as the notification.
205  UT_Array< ObserverPair > myObservers;
206 
207  // some state flags
208  bool myNotifyingFlag; // currently notifying observers
209  bool myPendingRemovalFlag; // list contains observers to remove
210 };
211 
212 // include the templated implementation
213 #include "UT_Notifier.C"
214 
215 #endif // __UT_Notifier_h__
virtual bool hasObserver(const UT_NotifierList &list) const
Definition: UT_Notifier.C:50
int64 exint
Definition: SYS_Types.h:125
int64 getMemoryUsage(bool inclusive=false) const
Definition: UT_Array.h:469
void removeObserver(UT_NotifierList &list) override
Definition: UT_Notifier.C:81
#define UT_API
Definition: UT_API.h:13
virtual void notifyObservers(EVENT_TYPE event)
Definition: UT_Notifier.C:140
virtual ~UT_Notifier()
Definition: UT_Notifier.h:91
UT_Functor1< void, EVENT_TYPE > Callback
Definition: UT_Notifier.h:104
~UT_NotifierImpl() override
Definition: UT_Notifier.C:28
long long int64
Definition: SYS_Types.h:116
exint entries() const
Alias of size(). size() is preferred.
Definition: UT_Array.h:460
cl_event event
Definition: glew.h:3695
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:157
virtual void addObserver(UT_NotifierList &list, Callback &callback)
Definition: UT_Notifier.C:58