OpenWalnut  1.3.1
WPropertyObserver.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WPROPERTYOBSERVER_H
26 #define WPROPERTYOBSERVER_H
27 
28 #include <map>
29 #include <string>
30 #include <set>
31 
32 #include <boost/signals2/signal.hpp>
33 #include <boost/thread.hpp>
34 
35 #include "WCondition.h"
36 #include "WProperties.h"
37 
38 
39 /**
40  * This class can observe properties inside a property group. The property group to observer can simply be set and replaced comfortably. Whenever
41  * one of the child properties updates, the observer fires too. If the observed property group itself
42  * changes (added properties, removed properties and so on), the observer gets updated automatically.
43  */
45 {
46 public:
47  /**
48  * Convenience type for a set of property instances.
49  */
50  typedef std::map< std::string, boost::shared_ptr< WPropertyBase > > PropertyNameMap;
51 
52  /**
53  * Default constructor.
54  */
56 
57  /**
58  * Destructor.
59  */
60  virtual ~WPropertyObserver();
61 
62  /**
63  * Defines the property group whose children should be watched. You can define a list of names manually if you are not interested in updates
64  * of ALL properties.
65  * \note this also resets the updated flag and the list of the last fired properties.
66  *
67  * \param properties the group whose children should be watched.
68  * \param names list of names. If specified, only these properties are observed.
69  */
70  void observe( boost::shared_ptr< WProperties > properties, std::set< std::string > names = std::set< std::string >() );
71 
72  /**
73  * Is true if one observed property fired. This is reset by the \ref handled method.
74  *
75  * \return true if one property fired.
76  */
77  bool updated() const;
78 
79  /**
80  * Resets the update flag and the list of fired properties.
81  *
82  * \return the set of properties fired until the last call of \ref handled.
83  */
85 
86  /**
87  * Creates a new instance of WPropertyObserver. Useful to save some typing as it creates an shared pointer for you.
88  *
89  * \return the new instance.
90  */
91  static boost::shared_ptr< WPropertyObserver > create();
92 
93 protected:
94 private:
95  /**
96  * Disallow copy construction.
97  *
98  * \param rhs the other threaded runner.
99  */
100  WPropertyObserver( const WPropertyObserver& rhs );
101 
102  /**
103  * Disallow copy assignment.
104  *
105  * \param rhs the other threaded runner.
106  * \return this.
107  */
109 
110  /**
111  * Cancels all current subscriptions and cleans m_subscriptions.
112  */
113  void cancelSubscriptions();
114 
115  /**
116  * Subscribes each property update condition which matches an entry in m_propNames.
117  */
118  void updateSubscriptions();
119 
120  /**
121  * Gets called by the update callback of the property. The property given as parameter was the property that fired.
122  *
123  * \param property the property that fired.
124  */
125  void propertyUpdated( boost::shared_ptr< WPropertyBase > property );
126 
127  /**
128  * Type for shared container with signal connections.
129  */
131 
132  /**
133  * The subscription to each property which was subscribed.
134  */
136 
137  /**
138  * True if a property fired.
139  */
140  bool m_updated;
141 
142  /**
143  * The properties handled by this observer.
144  */
145  boost::shared_ptr< WProperties > m_properties;
146 
147  /**
148  * The names of the properties which shall be observed if they are or become available.
149  */
150  std::set< std::string > m_propNames;
151 
152  /**
153  * The connection used to get notified about m_properties updates.
154  */
155  boost::signals2::scoped_connection m_updateConditionConnection;
156 
157  /**
158  * Type of shared container for the list of last updated properties.
159  */
161 
162  /**
163  * The queue of properties that fired before handled() is called.
164  */
166 };
167 
168 #endif // WPROPERTYOBSERVER_H
169