OpenWalnut  1.4.0
WModuleInputConnector.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 WMODULEINPUTCONNECTOR_H
26 #define WMODULEINPUTCONNECTOR_H
27 
28 #include <string>
29 
30 #include <boost/thread/locks.hpp>
31 
32 class WModule;
33 #include "WModuleConnector.h"
34 
35 class WCondition;
36 
37 
38 
39 /**
40  * Class implementing input connection functionality between modules.
41  */
43 {
44 public:
45  /**
46  * Constructor.
47  *
48  * \param module the module which is owner of this connector.
49  * \param name The name of this connector.
50  * \param description Short description of this connector.
51  */
52  WModuleInputConnector( boost::shared_ptr< WModule > module, std::string name="", std::string description="" );
53 
54  /**
55  * Destructor.
56  */
57  virtual ~WModuleInputConnector();
58 
59  /**
60  * Checks whether the specified connector is an output connector.
61  *
62  * \param con the connector to check against.
63  *
64  * \return true if compatible.
65  */
66  virtual bool connectable( boost::shared_ptr<WModuleConnector> con );
67 
68  /**
69  * Gets the condition variable that gets fired whenever new data has been sent.
70  *
71  * \return the condition
72  */
73  boost::shared_ptr< WCondition > getDataChangedCondition();
74 
75  /**
76  * Connects (subscribes) a specified notify function with a signal this module instance is offering.
77  *
78  * \exception WModuleSignalSubscriptionFailed thrown if the signal can't be connected.
79  *
80  * \param signal the signal to connect to.
81  * \param notifier the notifier function to bind.
82  *
83  * \return the connection. Disconnect it manually if not needed anymore!
84  */
85  boost::signals2::connection subscribeSignal( MODULE_CONNECTOR_SIGNAL signal, t_GenericSignalHandlerType notifier );
86 
87  /**
88  * Returns true if this instance is an WModuleInputConnector.
89  *
90  * \return true if castable to WModuleInputConnector.
91  */
92  virtual bool isInputConnector() const;
93 
94  /**
95  * Returns true if this instance is an WModuleOutputConnector.
96  *
97  * \return true if castable to WModuleOutputConnector.
98  */
99  virtual bool isOutputConnector() const;
100 
101  /**
102  * Denotes whether the connected output was updated. This does NOT denote an actual change in the current data!
103  *
104  * \return true if there has been an update.
105  */
106  virtual bool updated();
107 
108  /**
109  * Resets the updated-flag. Call this from your module to reset the value of updated().
110  *
111  * \return the update flag before reset. Useful to get the flag and reset it in one call.
112  */
113  virtual bool handledUpdate();
114 
115 protected:
116  /**
117  * Connect additional signals.
118  *
119  * \param con the connector that requests connection.
120  *
121  */
122  virtual void connectSignals( boost::shared_ptr<WModuleConnector> con );
123 
124  /**
125  * Disconnect all signals subscribed by this connector from "con".
126  *
127  * \param con the connector that gets disconnected.
128  */
129  virtual void disconnectSignals( boost::shared_ptr<WModuleConnector> con );
130 
131  /**
132  * Gets called when the data on this input connector changed.
133  *
134  * \param input the input connector receiving the change.
135  * \param output the output connector sending the change notification.
136  */
137  virtual void notifyDataChange( boost::shared_ptr<WModuleConnector> input, boost::shared_ptr<WModuleConnector> output );
138 
139  /**
140  * Gets called whenever a connector gets connected to the specified input.
141  *
142  * \param here the connector of THIS module that got connected to "there"
143  * \param there the connector that has been connected with the connector "here" of this module.
144  */
145  virtual void notifyConnectionEstablished( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there );
146 
147  /**
148  * Sets the update flag (use updated() to query it)to true. This is normally called by the notifyDataChange callback.
149  */
150  virtual void setUpdated();
151 
152 private:
153  /**
154  * Signal for "DATA_CHANGED" Events. We use a separate signal here (instead of using the signal send by the connected output)
155  * since the output can not determine the receiver when signalling. So we use an own signal handler and signal to "forward"
156  * the message and complete the information with a this-pointer.
157  */
158  t_GenericSignalType signal_DataChanged;
159 
160  /**
161  * Condition fired whenever data changes.
162  */
163  boost::shared_ptr< WCondition > m_dataChangedCondition;
164 
165  /**
166  * Connection for Data Changed signal of the connected output connector.
167  */
168  boost::signals2::connection m_DataChangedConnection;
169 
170  /**
171  * This lock protects the m_updated flag.
172  */
173  boost::shared_mutex m_updatedLock;
174 
175  /**
176  * A flag denoting that an update was received. It does not denote a real change in the value!
177  */
178  bool m_updated;
179 };
180 
181 #endif // WMODULEINPUTCONNECTOR_H
182