OpenWalnut  1.4.0
WModuleInputConnector.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 WMODULEINPUTCONNECTOR_H
00026 #define WMODULEINPUTCONNECTOR_H
00027 
00028 #include <string>
00029 
00030 #include <boost/thread/locks.hpp>
00031 
00032 class WModule;
00033 #include "WModuleConnector.h"
00034 
00035 class WCondition;
00036 
00037 
00038 
00039 /**
00040  * Class implementing input connection functionality between modules.
00041  */
00042 class  WModuleInputConnector: public WModuleConnector
00043 {
00044 public:
00045     /**
00046      * Constructor.
00047      *
00048      * \param module the module which is owner of this connector.
00049      * \param name The name of this connector.
00050      * \param description Short description of this connector.
00051      */
00052     WModuleInputConnector( boost::shared_ptr< WModule > module, std::string name="", std::string description="" );
00053 
00054     /**
00055      * Destructor.
00056      */
00057     virtual ~WModuleInputConnector();
00058 
00059     /**
00060      * Checks whether the specified connector is an output connector.
00061      *
00062      * \param con the connector to check against.
00063      *
00064      * \return true if compatible.
00065      */
00066     virtual bool connectable( boost::shared_ptr<WModuleConnector> con );
00067 
00068     /**
00069      * Gets the condition variable that gets fired whenever new data has been sent.
00070      *
00071      * \return the condition
00072      */
00073     boost::shared_ptr< WCondition > getDataChangedCondition();
00074 
00075     /**
00076      * Connects (subscribes) a specified notify function with a signal this module instance is offering.
00077      *
00078      * \exception WModuleSignalSubscriptionFailed thrown if the signal can't be connected.
00079      *
00080      * \param signal the signal to connect to.
00081      * \param notifier the notifier function to bind.
00082      *
00083      * \return the connection. Disconnect it manually if not needed anymore!
00084      */
00085     boost::signals2::connection subscribeSignal( MODULE_CONNECTOR_SIGNAL signal, t_GenericSignalHandlerType notifier );
00086 
00087     /**
00088      * Returns true if this instance is an WModuleInputConnector.
00089      *
00090      * \return true if castable to WModuleInputConnector.
00091      */
00092     virtual bool isInputConnector() const;
00093 
00094     /**
00095      * Returns true if this instance is an WModuleOutputConnector.
00096      *
00097      * \return true if castable to WModuleOutputConnector.
00098      */
00099     virtual bool isOutputConnector() const;
00100 
00101     /**
00102      * Denotes whether the connected output was updated. This does NOT denote an actual change in the current data!
00103      *
00104      * \return true if there has been an update.
00105      */
00106     virtual bool updated();
00107 
00108     /**
00109      * Resets the updated-flag. Call this from your module to reset the value of updated().
00110      *
00111      * \return the update flag before reset. Useful to get the flag and reset it in one call.
00112      */
00113     virtual bool handledUpdate();
00114 
00115 protected:
00116     /**
00117      * Connect additional signals.
00118      *
00119      * \param con the connector that requests connection.
00120      *
00121      */
00122     virtual void connectSignals( boost::shared_ptr<WModuleConnector> con );
00123 
00124     /**
00125      * Disconnect all signals subscribed by this connector from "con".
00126      *
00127      * \param con the connector that gets disconnected.
00128      */
00129     virtual void disconnectSignals( boost::shared_ptr<WModuleConnector> con );
00130 
00131     /**
00132      * Gets called when the data on this input connector changed.
00133      *
00134      * \param input the input connector receiving the change.
00135      * \param output the output connector sending the change notification.
00136      */
00137     virtual void notifyDataChange( boost::shared_ptr<WModuleConnector> input, boost::shared_ptr<WModuleConnector> output );
00138 
00139     /**
00140      * Gets called whenever a connector gets connected to the specified input.
00141      *
00142      * \param here the connector of THIS module that got connected to "there"
00143      * \param there the connector that has been connected with the connector "here" of this module.
00144      */
00145     virtual void notifyConnectionEstablished( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there );
00146 
00147     /**
00148      * Sets the update flag (use updated() to query it)to true. This is normally called by the notifyDataChange callback.
00149      */
00150     virtual void setUpdated();
00151 
00152 private:
00153     /**
00154      * Signal for "DATA_CHANGED" Events. We use a separate signal here (instead of using the signal send by the connected output)
00155      * since the output can not determine the receiver when signalling. So we use an own signal handler and signal to "forward"
00156      * the message and complete the information with a this-pointer.
00157      */
00158     t_GenericSignalType signal_DataChanged;
00159 
00160     /**
00161      * Condition fired whenever data changes.
00162      */
00163     boost::shared_ptr< WCondition > m_dataChangedCondition;
00164 
00165     /**
00166      * Connection for Data Changed signal of the connected output connector.
00167      */
00168     boost::signals2::connection m_DataChangedConnection;
00169 
00170     /**
00171      * This lock protects the m_updated flag.
00172      */
00173     boost::shared_mutex m_updatedLock;
00174 
00175     /**
00176      * A flag denoting that an update was received. It does not denote a real change in the value!
00177      */
00178     bool m_updated;
00179 };
00180 
00181 #endif  // WMODULEINPUTCONNECTOR_H
00182