OpenWalnut
1.4.0
|
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 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 WModuleConnector: public boost::enable_shared_from_this<WModuleConnector> 00051 { 00052 friend class WModuleConnectorTest; 00053 friend class WModuleProjectFileCombiner; 00054 00055 public: 00056 /** 00057 * Shared pointer to this class. 00058 */ 00059 typedef boost::shared_ptr< WModuleConnector > SPtr; 00060 00061 /** 00062 * Const shared pointer to this class. 00063 */ 00064 typedef boost::shared_ptr< const WModuleConnector > ConstSPtr; 00065 00066 /** 00067 * Constructor. 00068 * 00069 * \param module the module which is owner of this connector. 00070 * \param name The name of this connector. 00071 * \param description Short description of this connector. 00072 */ 00073 WModuleConnector( boost::shared_ptr< WModule > module, std::string name="", std::string description="" ); 00074 00075 /** 00076 * Destructor. 00077 */ 00078 virtual ~WModuleConnector(); 00079 00080 /** 00081 * Returns the module which owns this connector. 00082 * 00083 * \return the module owning the connector. 00084 */ 00085 boost::shared_ptr< WModule > getModule() const; 00086 00087 /** 00088 * Disconnects this connector if connected. If it is not connected: nothing happens. 00089 * 00090 * \param con the connector to disconnect. 00091 * \param removeFromOwnList if true the specified connection is also removed from the own connection list. If false it won't. 00092 */ 00093 virtual void disconnect( boost::shared_ptr<WModuleConnector> con, bool removeFromOwnList = true ); 00094 00095 /** 00096 * Disconnects ALL connected connectors. 00097 */ 00098 virtual void disconnectAll(); 00099 00100 /** 00101 * Connects this Module Connector with another one. During connection process, just the connectibility flag from 00102 * WModuleConnector::connectable is used to determine whether the connection is possible or not. 00103 * 00104 * \param con the connector to connect. 00105 * 00106 * \exception WModuleConnectionFailed if connection can not be established. 00107 * 00108 * \return true if successful 00109 */ 00110 virtual void connect( boost::shared_ptr<WModuleConnector> con ); 00111 00112 /** 00113 * Checks whether this connector is connected to the given one. If there is the strange case where one connector is connected 00114 * with the other one but not vice versa it will throw an exception. 00115 * 00116 * \param con the connector to check connection with. 00117 * 00118 * \return true if connected 00119 * 00120 * \throw WModuleConnectionInvalid thrown if one connector thinks it is connected but the other one not. 00121 */ 00122 bool isConnectedTo( boost::shared_ptr<WModuleConnector> con ); 00123 00124 /** 00125 * Gets the count of connections currently established. 00126 * 00127 * \return the number of connections. 00128 */ 00129 unsigned int isConnected(); 00130 00131 /** 00132 * Connects a specified notify function with a signal this module instance is offering. 00133 * 00134 * \exception WSignalSubscriptionFailed thrown if the signal can't be connected. 00135 * 00136 * \param signal the signal to connect to. 00137 * \param notifier the notifier function to bind. 00138 * 00139 * \return connection descriptor. 00140 */ 00141 virtual boost::signals2::connection subscribeSignal( MODULE_CONNECTOR_SIGNAL signal, t_GenericSignalHandlerType notifier ); 00142 00143 /** 00144 * Gives information about this connection. 00145 * 00146 * \return The connection's description. 00147 */ 00148 const std::string getDescription() const; 00149 00150 /** 00151 * Sets the connector's description. This is not thread-safe! Do not use it outside the WModule thread. 00152 * 00153 * \param desc the new description. 00154 */ 00155 void setDescription( std::string desc ); 00156 00157 /** 00158 * Gives name of connection. 00159 * 00160 * \return The name of this connection 00161 */ 00162 const std::string getName() const; 00163 00164 /** 00165 * Gives canonical name of connection. The canonical name is a descriptor including module name. The description is 00166 * ModuleName:ConnectorName. 00167 * 00168 * \return The name of this connection 00169 */ 00170 const std::string getCanonicalName() const; 00171 00172 /** 00173 * Sets the connector's name. This is not thread-safe! Do not use it outside the WModule thread. 00174 * 00175 * \param name the new name. 00176 */ 00177 void setName( std::string name ); 00178 00179 /** 00180 * Checks whether the specified connector is connectable to this one. 00181 * 00182 * \param con the connector to check against. 00183 * 00184 * \return true if compatible. 00185 */ 00186 virtual bool connectable( boost::shared_ptr<WModuleConnector> con ) = 0; 00187 00188 /** 00189 * Returns a list of possible disconnections for this connector. Please be aware that the connections might change during the life-time of 00190 * the returned DisconnectCombiner instances. 00191 * 00192 * \return the possible disconnections. 00193 */ 00194 WCombinerTypes::WOneToOneCombiners getPossibleDisconnections(); 00195 00196 /** 00197 * Tries to convert this instance to an input connector. 00198 * 00199 * \return this as input connector 00200 */ 00201 boost::shared_ptr< WModuleInputConnector > toInputConnector(); 00202 00203 /** 00204 * Tries to convert this instance to an output connector. 00205 * 00206 * \return this as output connector 00207 */ 00208 boost::shared_ptr< WModuleOutputConnector > toOutputConnector(); 00209 00210 /** 00211 * Returns true if this instance is an WModuleInputConnector. 00212 * 00213 * \return true if castable to WModuleInputConnector. 00214 */ 00215 virtual bool isInputConnector() const = 0; 00216 00217 /** 00218 * Returns true if this instance is an WModuleOutputConnector. 00219 * 00220 * \return true if castable to WModuleOutputConnector. 00221 */ 00222 virtual bool isOutputConnector() const = 0; 00223 00224 protected: 00225 /** 00226 * List of connectors connected to this connector. 00227 */ 00228 std::set<boost::shared_ptr<WModuleConnector> > m_connected; 00229 00230 /** 00231 * Lock for avoiding concurrent write to m_Connected (multiple reader, single writer lock). The read lock can be acquired using 00232 * the boost::shared_lock<boost::shared_mutex> lock( m_ConnectionListLock );. 00233 */ 00234 boost::shared_mutex m_connectionListLock; 00235 00236 /** 00237 * Connect additional signals. 00238 * 00239 * \param con the connector that requests connection. 00240 * 00241 */ 00242 virtual void connectSignals( boost::shared_ptr<WModuleConnector> con ); 00243 00244 /** 00245 * Disconnect all signals subscribed by this connector from "con". 00246 * 00247 * \param con the connector that gets disconnected. 00248 */ 00249 virtual void disconnectSignals( boost::shared_ptr<WModuleConnector> con ); 00250 00251 /** 00252 * Gives the signal handler function responsible for a given signal. Modules defining own signal handlers should overwrite 00253 * this function. This function is protected since boost::functions are callable, which is what is not wanted here. Just 00254 * signals should call them. 00255 * 00256 * \param signal the signal to get the handler for. 00257 * 00258 * \return the signal handler for "signal". 00259 */ 00260 virtual const t_GenericSignalHandlerType getSignalHandler( MODULE_CONNECTOR_SIGNAL signal ); 00261 00262 /** 00263 * The Module this connector belongs to 00264 */ 00265 boost::weak_ptr< WModule > m_module; 00266 00267 /** 00268 * The name of the module owning this connector. 00269 */ 00270 std::string m_moduleName; 00271 00272 /** 00273 * Gets called whenever a connector gets connected to the specified input. 00274 * 00275 * \param here the connector of THIS module that got connected to "there" 00276 * \param there the connector that has been connected with the connector "here" of this module. 00277 */ 00278 virtual void notifyConnectionEstablished( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there ); 00279 00280 /** 00281 * Gets called whenever a connection between a remote and local connector gets closed. 00282 * 00283 * \param here the connector of THIS module getting disconnected. 00284 * \param there the connector of the other module getting disconnected. 00285 */ 00286 virtual void notifyConnectionClosed( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there ); 00287 00288 /** 00289 * Signal emitted whenever connection has been established. 00290 */ 00291 t_GenericSignalType signal_ConnectionEstablished; 00292 00293 /** 00294 * Signal emitted whenever connection has been closed. 00295 */ 00296 t_GenericSignalType signal_ConnectionClosed; 00297 00298 private: 00299 /** 00300 * The connections name. 00301 */ 00302 std::string m_name; 00303 00304 /** 00305 * The connections description. 00306 */ 00307 std::string m_description; 00308 }; 00309 00310 #endif // WMODULECONNECTOR_H 00311