OpenWalnut  1.4.0
WModuleConnector.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 WMODULECONNECTOR_H
26 #define WMODULECONNECTOR_H
27 
28 #include <set>
29 #include <string>
30 
31 #ifndef Q_MOC_RUN
32 #include <boost/shared_ptr.hpp>
33 #endif
34 #ifndef Q_MOC_RUN
35 #include <boost/thread.hpp>
36 #endif
37 #ifndef Q_MOC_RUN
38 #include <boost/signals2/signal.hpp>
39 #endif
40 #ifndef Q_MOC_RUN
41 #include <boost/signals2/connection.hpp>
42 #endif
43 #ifndef Q_MOC_RUN
44 #include <boost/bind.hpp>
45 #endif
46 
47 #include "WModule.h"
48 #include "WModuleCombinerTypes.h"
49 #include "WModuleConnectorSignals.h"
50 
51 
52 
55 
56 /**
57  * Base class for modelling connections between kernel modules. It contains several pure virtual member functions and can
58  * therefore not instantiated directly.
59  */
60 class WModuleConnector: public boost::enable_shared_from_this<WModuleConnector>
61 {
62 friend class WModuleConnectorTest;
63 friend class WModuleProjectFileCombiner;
64 
65 public:
66  /**
67  * Shared pointer to this class.
68  */
69  typedef boost::shared_ptr< WModuleConnector > SPtr;
70 
71  /**
72  * Const shared pointer to this class.
73  */
74  typedef boost::shared_ptr< const WModuleConnector > ConstSPtr;
75 
76  /**
77  * Constructor.
78  *
79  * \param module the module which is owner of this connector.
80  * \param name The name of this connector.
81  * \param description Short description of this connector.
82  */
83  WModuleConnector( boost::shared_ptr< WModule > module, std::string name="", std::string description="" );
84 
85  /**
86  * Destructor.
87  */
88  virtual ~WModuleConnector();
89 
90  /**
91  * Returns the module which owns this connector.
92  *
93  * \return the module owning the connector.
94  */
95  boost::shared_ptr< WModule > getModule() const;
96 
97  /**
98  * Disconnects this connector if connected. If it is not connected: nothing happens.
99  *
100  * \param con the connector to disconnect.
101  * \param removeFromOwnList if true the specified connection is also removed from the own connection list. If false it won't.
102  */
103  virtual void disconnect( boost::shared_ptr<WModuleConnector> con, bool removeFromOwnList = true );
104 
105  /**
106  * Disconnects ALL connected connectors.
107  */
108  virtual void disconnectAll();
109 
110  /**
111  * Connects this Module Connector with another one. During connection process, just the connectibility flag from
112  * WModuleConnector::connectable is used to determine whether the connection is possible or not.
113  *
114  * \param con the connector to connect.
115  *
116  * \exception WModuleConnectionFailed if connection can not be established.
117  *
118  * \return true if successful
119  */
120  virtual void connect( boost::shared_ptr<WModuleConnector> con );
121 
122  /**
123  * Checks whether this connector is connected to the given one. If there is the strange case where one connector is connected
124  * with the other one but not vice versa it will throw an exception.
125  *
126  * \param con the connector to check connection with.
127  *
128  * \return true if connected
129  *
130  * \throw WModuleConnectionInvalid thrown if one connector thinks it is connected but the other one not.
131  */
132  bool isConnectedTo( boost::shared_ptr<WModuleConnector> con );
133 
134  /**
135  * Gets the count of connections currently established.
136  *
137  * \return the number of connections.
138  */
139  unsigned int isConnected();
140 
141  /**
142  * Connects a specified notify function with a signal this module instance is offering.
143  *
144  * \exception WSignalSubscriptionFailed thrown if the signal can't be connected.
145  *
146  * \param signal the signal to connect to.
147  * \param notifier the notifier function to bind.
148  *
149  * \return connection descriptor.
150  */
151  virtual boost::signals2::connection subscribeSignal( MODULE_CONNECTOR_SIGNAL signal, t_GenericSignalHandlerType notifier );
152 
153  /**
154  * Gives information about this connection.
155  *
156  * \return The connection's description.
157  */
158  const std::string getDescription() const;
159 
160  /**
161  * Sets the connector's description. This is not thread-safe! Do not use it outside the WModule thread.
162  *
163  * \param desc the new description.
164  */
165  void setDescription( std::string desc );
166 
167  /**
168  * Gives name of connection.
169  *
170  * \return The name of this connection
171  */
172  const std::string getName() const;
173 
174  /**
175  * Gives canonical name of connection. The canonical name is a descriptor including module name. The description is
176  * ModuleName:ConnectorName.
177  *
178  * \return The name of this connection
179  */
180  const std::string getCanonicalName() const;
181 
182  /**
183  * Sets the connector's name. This is not thread-safe! Do not use it outside the WModule thread.
184  *
185  * \param name the new name.
186  */
187  void setName( std::string name );
188 
189  /**
190  * Checks whether the specified connector is connectable to this one.
191  *
192  * \param con the connector to check against.
193  *
194  * \return true if compatible.
195  */
196  virtual bool connectable( boost::shared_ptr<WModuleConnector> con ) = 0;
197 
198  /**
199  * Returns a list of possible disconnections for this connector. Please be aware that the connections might change during the life-time of
200  * the returned DisconnectCombiner instances.
201  *
202  * \return the possible disconnections.
203  */
204  WCombinerTypes::WOneToOneCombiners getPossibleDisconnections();
205 
206  /**
207  * Tries to convert this instance to an input connector.
208  *
209  * \return this as input connector
210  */
211  boost::shared_ptr< WModuleInputConnector > toInputConnector();
212 
213  /**
214  * Tries to convert this instance to an output connector.
215  *
216  * \return this as output connector
217  */
218  boost::shared_ptr< WModuleOutputConnector > toOutputConnector();
219 
220  /**
221  * Returns true if this instance is an WModuleInputConnector.
222  *
223  * \return true if castable to WModuleInputConnector.
224  */
225  virtual bool isInputConnector() const = 0;
226 
227  /**
228  * Returns true if this instance is an WModuleOutputConnector.
229  *
230  * \return true if castable to WModuleOutputConnector.
231  */
232  virtual bool isOutputConnector() const = 0;
233 
234 protected:
235  /**
236  * List of connectors connected to this connector.
237  */
238  std::set<boost::shared_ptr<WModuleConnector> > m_connected;
239 
240  /**
241  * Lock for avoiding concurrent write to m_Connected (multiple reader, single writer lock). The read lock can be acquired using
242  * the boost::shared_lock<boost::shared_mutex> lock( m_ConnectionListLock );.
243  */
244  boost::shared_mutex m_connectionListLock;
245 
246  /**
247  * Connect additional signals.
248  *
249  * \param con the connector that requests connection.
250  *
251  */
252  virtual void connectSignals( boost::shared_ptr<WModuleConnector> con );
253 
254  /**
255  * Disconnect all signals subscribed by this connector from "con".
256  *
257  * \param con the connector that gets disconnected.
258  */
259  virtual void disconnectSignals( boost::shared_ptr<WModuleConnector> con );
260 
261  /**
262  * Gives the signal handler function responsible for a given signal. Modules defining own signal handlers should overwrite
263  * this function. This function is protected since boost::functions are callable, which is what is not wanted here. Just
264  * signals should call them.
265  *
266  * \param signal the signal to get the handler for.
267  *
268  * \return the signal handler for "signal".
269  */
270  virtual const t_GenericSignalHandlerType getSignalHandler( MODULE_CONNECTOR_SIGNAL signal );
271 
272  /**
273  * The Module this connector belongs to
274  */
275  boost::weak_ptr< WModule > m_module;
276 
277  /**
278  * The name of the module owning this connector.
279  */
280  std::string m_moduleName;
281 
282  /**
283  * Gets called whenever a connector gets connected to the specified input.
284  *
285  * \param here the connector of THIS module that got connected to "there"
286  * \param there the connector that has been connected with the connector "here" of this module.
287  */
288  virtual void notifyConnectionEstablished( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there );
289 
290  /**
291  * Gets called whenever a connection between a remote and local connector gets closed.
292  *
293  * \param here the connector of THIS module getting disconnected.
294  * \param there the connector of the other module getting disconnected.
295  */
296  virtual void notifyConnectionClosed( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there );
297 
298  /**
299  * Signal emitted whenever connection has been established.
300  */
301  t_GenericSignalType signal_ConnectionEstablished;
302 
303  /**
304  * Signal emitted whenever connection has been closed.
305  */
306  t_GenericSignalType signal_ConnectionClosed;
307 
308 private:
309  /**
310  * The connections name.
311  */
312  std::string m_name;
313 
314  /**
315  * The connections description.
316  */
317  std::string m_description;
318 };
319 
320 #endif // WMODULECONNECTOR_H
321 
t_GenericSignalType signal_ConnectionEstablished
Signal emitted whenever connection has been established.
virtual void disconnectAll()
Disconnects ALL connected connectors.
boost::shared_ptr< const WModuleConnector > ConstSPtr
Const shared pointer to this class.
virtual bool isInputConnector() const =0
Returns true if this instance is an WModuleInputConnector.
const std::string getName() const
Gives name of connection.
boost::weak_ptr< WModule > m_module
The Module this connector belongs to.
WModuleConnector(boost::shared_ptr< WModule > module, std::string name="", std::string description="")
Constructor.
std::string m_name
The connections name.
t_GenericSignalType signal_ConnectionClosed
Signal emitted whenever connection has been closed.
virtual void disconnect(boost::shared_ptr< WModuleConnector > con, bool removeFromOwnList=true)
Disconnects this connector if connected.
boost::shared_ptr< WModuleInputConnector > toInputConnector()
Tries to convert this instance to an input connector.
virtual void connect(boost::shared_ptr< WModuleConnector > con)
Connects this Module Connector with another one.
virtual bool connectable(boost::shared_ptr< WModuleConnector > con)=0
Checks whether the specified connector is connectable to this one.
unsigned int isConnected()
Gets the count of connections currently established.
std::string m_moduleName
The name of the module owning this connector.
This class is able to parse project files and create the appropriate module graph inside a specified ...
void setDescription(std::string desc)
Sets the connector's description.
const std::string getDescription() const
Gives information about this connection.
void setName(std::string name)
Sets the connector's name.
virtual ~WModuleConnector()
Destructor.
Tests the WModuleConnector class.
virtual void disconnectSignals(boost::shared_ptr< WModuleConnector > con)
Disconnect all signals subscribed by this connector from "con".
virtual const t_GenericSignalHandlerType getSignalHandler(MODULE_CONNECTOR_SIGNAL signal)
Gives the signal handler function responsible for a given signal.
const std::string getCanonicalName() const
Gives canonical name of connection.
boost::shared_ptr< WModuleConnector > SPtr
Shared pointer to this class.
virtual void notifyConnectionClosed(boost::shared_ptr< WModuleConnector > here, boost::shared_ptr< WModuleConnector > there)
Gets called whenever a connection between a remote and local connector gets closed.
Class implementing output connection functionality between modules.
boost::shared_mutex m_connectionListLock
Lock for avoiding concurrent write to m_Connected (multiple reader, single writer lock)...
WCombinerTypes::WOneToOneCombiners getPossibleDisconnections()
Returns a list of possible disconnections for this connector.
virtual void notifyConnectionEstablished(boost::shared_ptr< WModuleConnector > here, boost::shared_ptr< WModuleConnector > there)
Gets called whenever a connector gets connected to the specified input.
virtual void connectSignals(boost::shared_ptr< WModuleConnector > con)
Connect additional signals.
Class implementing input connection functionality between modules.
bool isConnectedTo(boost::shared_ptr< WModuleConnector > con)
Checks whether this connector is connected to the given one.
boost::shared_ptr< WModuleOutputConnector > toOutputConnector()
Tries to convert this instance to an output connector.
std::set< boost::shared_ptr< WModuleConnector > > m_connected
List of connectors connected to this connector.
std::string m_description
The connections description.
Base class for modelling connections between kernel modules.
virtual boost::signals2::connection subscribeSignal(MODULE_CONNECTOR_SIGNAL signal, t_GenericSignalHandlerType notifier)
Connects a specified notify function with a signal this module instance is offering.
virtual bool isOutputConnector() const =0
Returns true if this instance is an WModuleOutputConnector.
boost::shared_ptr< WModule > getModule() const
Returns the module which owns this connector.