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