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