00001 //--------------------------------------------------------------------------- 00002 // 00003 // Project: OpenWalnut ( http://www.openwalnut.org ) 00004 // 00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS 00006 // For more information see http://www.openwalnut.org/copying 00007 // 00008 // This file is part of OpenWalnut. 00009 // 00010 // OpenWalnut is free software: you can redistribute it and/or modify 00011 // it under the terms of the GNU Lesser General Public License as published by 00012 // the Free Software Foundation, either version 3 of the License, or 00013 // (at your option) any later version. 00014 // 00015 // OpenWalnut is distributed in the hope that it will be useful, 00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of 00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00018 // GNU Lesser General Public License for more details. 00019 // 00020 // You should have received a copy of the GNU Lesser General Public License 00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>. 00022 // 00023 //--------------------------------------------------------------------------- 00024 00025 #ifndef WMODULECONNECTOR_H 00026 #define WMODULECONNECTOR_H 00027 00028 #include <set> 00029 #include <string> 00030 00031 #include <boost/shared_ptr.hpp> 00032 #include <boost/thread.hpp> 00033 #include <boost/signals2/signal.hpp> 00034 #include <boost/signals2/connection.hpp> 00035 #include <boost/bind.hpp> 00036 00037 #include "WModule.h" 00038 #include "WModuleCombinerTypes.h" 00039 #include "WModuleConnectorSignals.h" 00040 00041 #include "WExportKernel.h" 00042 00043 class WModuleInputConnector; 00044 class WModuleOutputConnector; 00045 00046 /** 00047 * Base class for modelling connections between kernel modules. It contains several pure virtual member functions and can 00048 * therefore not instantiated directly. 00049 */ 00050 class OWKERNEL_EXPORT WModuleConnector: public boost::enable_shared_from_this<WModuleConnector> 00051 { 00052 friend class WModuleConnectorTest; 00053 friend class WModuleProjectFileCombiner; 00054 00055 public: 00056 00057 /** 00058 * Shared pointer to this class. 00059 */ 00060 typedef boost::shared_ptr< WModuleConnector > SPtr; 00061 00062 /** 00063 * Const shared pointer to this class. 00064 */ 00065 typedef boost::shared_ptr< const WModuleConnector > ConstSPtr; 00066 00067 /** 00068 * Constructor. 00069 * 00070 * \param module the module which is owner of this connector. 00071 * \param name The name of this connector. 00072 * \param description Short description of this connector. 00073 */ 00074 WModuleConnector( boost::shared_ptr< WModule > module, std::string name="", std::string description="" ); 00075 00076 /** 00077 * Destructor. 00078 */ 00079 virtual ~WModuleConnector(); 00080 00081 /** 00082 * Returns the module which owns this connector. 00083 * 00084 * \return the module owning the connector. 00085 */ 00086 boost::shared_ptr< WModule > getModule() const; 00087 00088 /** 00089 * Disconnects this connector if connected. If it is not connected: nothing happens. 00090 * 00091 * \param con the connector to disconnect. 00092 * \param removeFromOwnList if true the specified connection is also removed from the own connection list. If false it won't. 00093 */ 00094 virtual void disconnect( boost::shared_ptr<WModuleConnector> con, bool removeFromOwnList = true ); 00095 00096 /** 00097 * Disconnects ALL connected connectors. 00098 */ 00099 virtual void disconnectAll(); 00100 00101 /** 00102 * Connects this Module Connector with another one. During connection process, just the connectibility flag from 00103 * WModuleConnector::connectable is used to determine whether the connection is possible or not. 00104 * 00105 * \param con the connector to connect. 00106 * 00107 * \exception WModuleConnectionFailed if connection can not be established. 00108 * 00109 * \return true if successful 00110 */ 00111 virtual void connect( boost::shared_ptr<WModuleConnector> con ); 00112 00113 /** 00114 * Checks whether this connector is connected to the given one. If there is the strange case where one connector is connected 00115 * with the other one but not vice versa it will throw an exception. 00116 * 00117 * \param con the connector to check connection with. 00118 * 00119 * \return true if connected 00120 * 00121 * \throw WModuleConnectionInvalid thrown if one connector thinks it is connected but the other one not. 00122 */ 00123 bool isConnectedTo( boost::shared_ptr<WModuleConnector> con ); 00124 00125 /** 00126 * Gets the count of connections currently established. 00127 * 00128 * \return the number of connections. 00129 */ 00130 unsigned int isConnected(); 00131 00132 /** 00133 * Connects a specified notify function with a signal this module instance is offering. 00134 * 00135 * \exception WModuleSignalSubscriptionFailed thrown if the signal can't be connected. 00136 * 00137 * \param signal the signal to connect to. 00138 * \param notifier the notifier function to bind. 00139 * 00140 * \return connection descriptor. 00141 */ 00142 virtual boost::signals2::connection subscribeSignal( MODULE_CONNECTOR_SIGNAL signal, t_GenericSignalHandlerType notifier ); 00143 00144 /** 00145 * Gives information about this connection. 00146 * 00147 * \return The connection's description. 00148 */ 00149 const std::string getDescription() const; 00150 00151 /** 00152 * Sets the connector's description. This is not thread-safe! Do not use it outside the WModule thread. 00153 * 00154 * \param desc the new description. 00155 */ 00156 void setDescription( std::string desc ); 00157 00158 /** 00159 * Gives name of connection. 00160 * 00161 * \return The name of this connection 00162 */ 00163 const std::string getName() const; 00164 00165 /** 00166 * Gives canonical name of connection. The canonical name is a descriptor including module name. The description is 00167 * ModuleName:ConnectorName. 00168 * 00169 * \return The name of this connection 00170 */ 00171 const std::string getCanonicalName() const; 00172 00173 /** 00174 * Sets the connector's name. This is not thread-safe! Do not use it outside the WModule thread. 00175 * 00176 * \param name the new name. 00177 */ 00178 void setName( std::string name ); 00179 00180 /** 00181 * Checks whether the specified connector is connectable to this one. 00182 * 00183 * \param con the connector to check against. 00184 * 00185 * \return true if compatible. 00186 */ 00187 virtual bool connectable( boost::shared_ptr<WModuleConnector> con ) = 0; 00188 00189 /** 00190 * Returns a list of possible disconnections for this connector. Please be aware that the connections might change during the life-time of 00191 * the returned DisconnectCombiner instances. 00192 * 00193 * \return the possible disconnections. 00194 */ 00195 WCombinerTypes::WOneToOneCombiners getPossibleDisconnections(); 00196 00197 /** 00198 * Tries to convert this instance to an input connector. 00199 * 00200 * \return this as input connector 00201 */ 00202 boost::shared_ptr< WModuleInputConnector > toInputConnector(); 00203 00204 /** 00205 * Tries to convert this instance to an output connector. 00206 * 00207 * \return this as output connector 00208 */ 00209 boost::shared_ptr< WModuleOutputConnector > toOutputConnector(); 00210 00211 /** 00212 * Returns true if this instance is an WModuleInputConnector. 00213 * 00214 * \return true if castable to WModuleInputConnector. 00215 */ 00216 virtual bool isInputConnector() const = 0; 00217 00218 /** 00219 * Returns true if this instance is an WModuleOutputConnector. 00220 * 00221 * \return true if castable to WModuleOutputConnector. 00222 */ 00223 virtual bool isOutputConnector() const = 0; 00224 00225 protected: 00226 00227 /** 00228 * List of connectors connected to this connector. 00229 */ 00230 std::set<boost::shared_ptr<WModuleConnector> > m_connected; 00231 00232 /** 00233 * Lock for avoiding concurrent write to m_Connected (multiple reader, single writer lock). The read lock can be acquired using 00234 * the boost::shared_lock<boost::shared_mutex> lock( m_ConnectionListLock );. 00235 */ 00236 boost::shared_mutex m_connectionListLock; 00237 00238 /** 00239 * Connect additional signals. 00240 * 00241 * \param con the connector that requests connection. 00242 * 00243 */ 00244 virtual void connectSignals( boost::shared_ptr<WModuleConnector> con ); 00245 00246 /** 00247 * Disconnect all signals subscribed by this connector from "con". 00248 * 00249 * \param con the connector that gets disconnected. 00250 */ 00251 virtual void disconnectSignals( boost::shared_ptr<WModuleConnector> con ); 00252 00253 /** 00254 * Gives the signal handler function responsible for a given signal. Modules defining own signal handlers should overwrite 00255 * this function. This function is protected since boost::functions are callable, which is what is not wanted here. Just 00256 * signals should call them. 00257 * 00258 * \param signal the signal to get the handler for. 00259 * 00260 * \return the signal handler for "signal". 00261 */ 00262 virtual const t_GenericSignalHandlerType getSignalHandler( MODULE_CONNECTOR_SIGNAL signal ); 00263 00264 /** 00265 * The Module this connector belongs to 00266 */ 00267 boost::weak_ptr< WModule > m_module; 00268 00269 /** 00270 * The name of the module owning this connector. 00271 */ 00272 std::string m_moduleName; 00273 00274 /** 00275 * Gets called whenever a connector gets connected to the specified input. 00276 * 00277 * \param here the connector of THIS module that got connected to "there" 00278 * \param there the connector that has been connected with the connector "here" of this module. 00279 */ 00280 virtual void notifyConnectionEstablished( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there ); 00281 00282 /** 00283 * Gets called whenever a connection between a remote and local connector gets closed. 00284 * 00285 * \param here the connector of THIS module getting disconnected. 00286 * \param there the connector of the other module getting disconnected. 00287 */ 00288 virtual void notifyConnectionClosed( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there ); 00289 00290 /** 00291 * Signal emitted whenever connection has been established. 00292 */ 00293 t_GenericSignalType signal_ConnectionEstablished; 00294 00295 /** 00296 * Signal emitted whenever connection has been closed. 00297 */ 00298 t_GenericSignalType signal_ConnectionClosed; 00299 00300 private: 00301 00302 /** 00303 * The connections name. 00304 */ 00305 std::string m_name; 00306 00307 /** 00308 * The connections description. 00309 */ 00310 std::string m_description; 00311 }; 00312 00313 #endif // WMODULECONNECTOR_H 00314