OpenWalnut  1.4.0
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 #ifndef Q_MOC_RUN
33 #include <boost/signals2/signal.hpp>
34 #endif
35 #ifndef Q_MOC_RUN
36 #include <boost/thread.hpp>
37 #endif
38 
39 #include "WCondition.h"
40 #include "WProperties.h"
41 
42 
43 /**
44  * This class can observe properties inside a property group. The property group to observer can simply be set and replaced comfortably. Whenever
45  * one of the child properties updates, the observer fires too. If the observed property group itself
46  * changes (added properties, removed properties and so on), the observer gets updated automatically.
47  */
49 {
50 public:
51  /**
52  * Convenience type for a set of property instances.
53  */
54  typedef std::map< std::string, boost::shared_ptr< WPropertyBase > > PropertyNameMap;
55 
56  /**
57  * Convenience type for a shared pointer on property observers.
58  */
59  typedef boost::shared_ptr< WPropertyObserver > SPtr;
60 
61  /**
62  * Default constructor.
63  */
65 
66  /**
67  * Destructor.
68  */
69  virtual ~WPropertyObserver();
70 
71  /**
72  * Defines the property group whose children should be watched. You can define a list of names manually if you are not interested in updates
73  * of ALL properties.
74  * \note this also resets the updated flag and the list of the last fired properties.
75  *
76  * \param properties the group whose children should be watched.
77  * \param names list of names. If specified, only these properties are observed.
78  */
79  void observe( boost::shared_ptr< WProperties > properties, std::set< std::string > names = std::set< std::string >() );
80 
81  /**
82  * Is true if one observed property fired. This is reset by the \ref handled method.
83  *
84  * \return true if one property fired.
85  */
86  bool updated() const;
87 
88  /**
89  * Resets the update flag and the list of fired properties.
90  *
91  * \return the set of properties fired until the last call of \ref handled.
92  */
93  PropertyNameMap handled();
94 
95  /**
96  * Creates a new instance of WPropertyObserver. Useful to save some typing as it creates an shared pointer for you.
97  *
98  * \return the new instance.
99  */
100  static boost::shared_ptr< WPropertyObserver > create();
101 
102 protected:
103 private:
104  /**
105  * Disallow copy construction.
106  *
107  * \param rhs the other threaded runner.
108  */
109  WPropertyObserver( const WPropertyObserver& rhs );
110 
111  /**
112  * Disallow copy assignment.
113  *
114  * \param rhs the other threaded runner.
115  * \return this.
116  */
118 
119  /**
120  * Cancels all current subscriptions and cleans m_subscriptions.
121  */
122  void cancelSubscriptions();
123 
124  /**
125  * Subscribes each property update condition which matches an entry in m_propNames.
126  */
127  void updateSubscriptions();
128 
129  /**
130  * Gets called by the update callback of the property. The property given as parameter was the property that fired.
131  *
132  * \param property the property that fired.
133  */
134  void propertyUpdated( boost::shared_ptr< WPropertyBase > property );
135 
136  /**
137  * Type for shared container with signal connections.
138  */
140 
141  /**
142  * The subscription to each property which was subscribed.
143  */
144  Subscriptions m_subscriptions;
145 
146  /**
147  * True if a property fired.
148  */
149  bool m_updated;
150 
151  /**
152  * The properties handled by this observer.
153  */
154  boost::shared_ptr< WProperties > m_properties;
155 
156  /**
157  * The names of the properties which shall be observed if they are or become available.
158  */
159  std::set< std::string > m_propNames;
160 
161  /**
162  * The connection used to get notified about m_properties updates.
163  */
164  boost::signals2::scoped_connection m_updateConditionConnection;
165 
166  /**
167  * Type of shared container for the list of last updated properties.
168  */
170 
171  /**
172  * The queue of properties that fired before handled() is called.
173  */
174  LastUpdated m_lastUpdated;
175 };
176 
177 #endif // WPROPERTYOBSERVER_H
178 
boost::signals2::scoped_connection m_updateConditionConnection
The connection used to get notified about m_properties updates.
virtual ~WPropertyObserver()
Destructor.
void cancelSubscriptions()
Cancels all current subscriptions and cleans m_subscriptions.
std::map< std::string, boost::shared_ptr< WPropertyBase > > PropertyNameMap
Convenience type for a set of property instances.
static boost::shared_ptr< WPropertyObserver > create()
Creates a new instance of WPropertyObserver.
WPropertyObserver & operator=(const WPropertyObserver &rhs)
Disallow copy assignment.
WSharedAssociativeContainer< std::map< boost::shared_ptr< WPropertyBase >, boost::signals2::connection > > Subscriptions
Type for shared container with signal connections.
bool m_updated
True if a property fired.
LastUpdated m_lastUpdated
The queue of properties that fired before handled() is called.
bool updated() const
Is true if one observed property fired.
std::set< std::string > m_propNames
The names of the properties which shall be observed if they are or become available.
void observe(boost::shared_ptr< WProperties > properties, std::set< std::string > names=std::set< std::string >())
Defines the property group whose children should be watched.
PropertyNameMap handled()
Resets the update flag and the list of fired properties.
Class to encapsulate boost::condition_variable_any.
Definition: WCondition.h:47
This class can observe properties inside a property group.
This class provides a common interface for thread-safe access to associative containers (set...
WPropertyObserver()
Default constructor.
void updateSubscriptions()
Subscribes each property update condition which matches an entry in m_propNames.
void propertyUpdated(boost::shared_ptr< WPropertyBase > property)
Gets called by the update callback of the property.
boost::shared_ptr< WPropertyObserver > SPtr
Convenience type for a shared pointer on property observers.
WSharedAssociativeContainer< PropertyNameMap > LastUpdated
Type of shared container for the list of last updated properties.
Subscriptions m_subscriptions
The subscription to each property which was subscribed.
boost::shared_ptr< WProperties > m_properties
The properties handled by this observer.