OpenWalnut  1.2.5
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
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 #include "WExportCommon.h"
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  */
44 class OWCOMMON_EXPORT WPropertyObserver: public WCondition
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  */
84  PropertyNameMap handled();
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 
95 private:
96 
97  /**
98  * Disallow copy construction.
99  *
100  * \param rhs the other threaded runner.
101  */
102  WPropertyObserver( const WPropertyObserver& rhs );
103 
104  /**
105  * Disallow copy assignment.
106  *
107  * \param rhs the other threaded runner.
108  * \return this.
109  */
110  WPropertyObserver& operator=( const WPropertyObserver& rhs );
111 
112  /**
113  * Cancels all current subscriptions and cleans m_subscriptions.
114  */
115  void cancelSubscriptions();
116 
117  /**
118  * Subscribes each property update condition which matches an entry in m_propNames.
119  */
120  void updateSubscriptions();
121 
122  /**
123  * Gets called by the update callback of the property. The property given as parameter was the property that fired.
124  *
125  * \param property the property that fired.
126  */
127  void propertyUpdated( boost::shared_ptr< WPropertyBase > property );
128 
129  /**
130  * Type for shared container with signal connections.
131  */
133 
134  /**
135  * The subscription to each property which was subscribed.
136  */
138 
139  /**
140  * True if a property fired.
141  */
142  bool m_updated;
143 
144  /**
145  * The properties handled by this observer.
146  */
147  boost::shared_ptr< WProperties > m_properties;
148 
149  /**
150  * The names of the properties which shall be observed if they are or become available.
151  */
152  std::set< std::string > m_propNames;
153 
154  /**
155  * The connection used to get notified about m_properties updates.
156  */
157  boost::signals2::scoped_connection m_updateConditionConnection;
158 
159  /**
160  * Type of shared container for the list of last updated properties.
161  */
163 
164  /**
165  * The queue of properties that fired before handled() is called.
166  */
168 };
169 
170 #endif // WPROPERTYOBSERVER_H
171