OpenWalnut 1.2.5
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 #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 
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends