OpenWalnut  1.4.0
WModuleConnector.h
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