1 /*********************                                                        */
2 /*! \file listener.h
3  ** \verbatim
4  ** Top contributors (to current version):
5  **   Tim King, Andres Noetzli
6  ** This file is part of the CVC4 project.
7  ** Copyright (c) 2009-2019 by the authors listed in the file AUTHORS
8  ** in the top-level source directory) and their institutional affiliations.
9  ** All rights reserved.  See the file COPYING in the top-level source
10  ** directory for licensing information.\endverbatim
11  **
12  ** \brief Utility classes for listeners and collections of listeners.
13  **
14  ** Utilities for the development of a Listener interface class. This class
15  ** provides a single notification that must be overwritten. This file also
16  ** provides a utility class for a collection of listeners and an RAII style
17  ** Registration class for managing the relationship between Listeners
18  ** and the collection.
19  **/
20 
21 #include "cvc4_public.h"
22 
23 #ifndef __CVC4__LISTENER_H
24 #define __CVC4__LISTENER_H
25 
26 #include <list>
27 
28 namespace CVC4 {
29 
30 /**
31  * Listener interface class.
32  *
33  * The interface provides a notify() function.
34  */
35 class CVC4_PUBLIC Listener {
36 public:
37   Listener();
38   virtual ~Listener();
39 
40   /** Note that notify may throw arbitrary exceptions. */
41   virtual void notify() = 0;
42 };
43 
44 /**
45  * ListenerCollection is a list of Listener instances.
46  * One can add and remove Listeners.
47  *
48  * ListenerCollection does not own the memory of the Listeners.
49  * As a sanity check, it asserted that all of its listeners
50  * have been removed.
51  */
52 class CVC4_PUBLIC ListenerCollection {
53 public:
54   typedef std::list<Listener*> ListenerList;
55   typedef ListenerList::iterator iterator;
56 
57   /** Creates an empty listener collection. */
58   ListenerCollection();
59 
60   /**
61    * Destroys an iterator collection.
62    * If assertions are on, this throws an AssertionException if the collection
63    * is not empty().
64    */
65   ~ListenerCollection();
66 
67   /**
68    * This adds a listener to the current collection and returns
69    * an iterator to the listener in the collection.
70    * The user of the collection must call removeListener() using
71    * this iterator.
72    * The collection does not take over the memory for the listener.
73    */
74   iterator addListener(Listener* listener);
75 
76   /**
77    * Remove an listener using the iterator distributed when adding the
78    * listener.
79    */
80   void removeListener(iterator position);
81 
82   /** Calls notify() on all listeners in the collection. */
83   void notify();
84 
85   /** Returns true if the collection contains no listeners. */
86   bool empty() const;
87 
88   /**
89    * Registration is an RAII utility function for using Listener
90    * with ListenerCollection.
91    *
92    * On construction, the Registration takes a ListenerCollection,
93    * collection,
94    * and a Listener*, listener. It takes over the memory for listener. It then
95    * adds listener to collection. On destruction it removes listener and calls
96    * delete on listener.
97    *
98    * Because of this usage, a Registration must be destroyed before the
99    * ListenerCollection it is attached to.
100    */
101   class CVC4_PUBLIC Registration {
102   public:
103     Registration(ListenerCollection* collection, Listener* listener);
104     ~Registration();
105 
106   private:
107     Listener* d_listener;
108     ListenerCollection::iterator d_position;
109     ListenerCollection* d_collection;
110   };/* class CVC4::ListenerCollection::Registration */
111 
112 
113   /**
114    * Returns a new Registration given a Listener that is attached to this
115    * ListenerCollection. Management of the memory is handed to the user of
116    * this function. To remove the listener, call the destructor for the
117    * Registration.
118    */
119   Registration* registerListener(Listener* listener);
120 
121 private:
122 
123   /**
124    * Disabling the copy-constructor.
125    * The user of the class must be know to remove listeners on the collection.
126    * Allowing copies will only cause confusion.
127    */
128   ListenerCollection(const ListenerCollection& copy) = delete;
129 
130   /**
131    * Disabling the assignment operator.
132    * The user of the class must be know to remove listeners on the collection.
133    * Allowing copies will only cause confusion.
134    */
135   ListenerCollection& operator=(const ListenerCollection& copy) = delete;
136 
137   /** A list of the listeners in the collection.*/
138   ListenerList d_listeners;
139 };/* class CVC4::ListenerCollection */
140 
141 /**
142  * A list of ListenerCollection::Registration* pointers.
143  *
144  * This list assumes it has control over all of the memory of the registrations.
145  */
146 class ListenerRegistrationList {
147  public:
148   ListenerRegistrationList();
149   ~ListenerRegistrationList();
150 
151   void add(ListenerCollection::Registration* registration);
152   void clear();
153 
154  private:
155   /** Disallow copying.*/
156   ListenerRegistrationList(const ListenerRegistrationList&) = delete;
157   /** Disallow assignment.*/
158   ListenerRegistrationList operator=(const ListenerRegistrationList&) = delete;
159   std::list<ListenerCollection::Registration*> d_registrations;
160 };/* class CVC4::ListenerRegistrationList */
161 
162 }/* CVC4 namespace */
163 
164 #endif /* __CVC4__LISTENER_H */
165