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