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