WModuleConnector.h 8.12 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
//---------------------------------------------------------------------------
//
// Project: OpenWalnut ( http://www.openwalnut.org )
//
// Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
// For more information see http://www.openwalnut.org/copying
//
// This file is part of OpenWalnut.
//
// OpenWalnut is free software: you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// OpenWalnut is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
//
//---------------------------------------------------------------------------

#ifndef WMODULECONNECTOR_H
#define WMODULECONNECTOR_H

#include <set>
29
#include <string>
30 31 32

#include <boost/shared_ptr.hpp>
#include <boost/thread.hpp>
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
33 34
#include <boost/signals2/signal.hpp>
#include <boost/signals2/connection.hpp>
35 36
#include <boost/bind.hpp>

37
#include "WModule.h"
38
#include "WModuleConnectorSignals.h"
39

40 41 42 43
/**
 * Base class for modelling connections between kernel modules. It contains several pure virtual member functions and can
 * therefore not instantiated directly.
 */
44
class WModuleConnector: public boost::enable_shared_from_this<WModuleConnector>
45
{
46
friend class WModuleConnectorTest;
47 48
friend class WModuleProjectFileCombiner;

49 50
public:

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
51
    /**
52
     * Constructor.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
53
     *
54 55 56
     * \param module the module which is owner of this connector.
     * \param name The name of this connector.
     * \param description Short description of this connector.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
57
     */
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
58
    WModuleConnector( boost::shared_ptr< WModule > module, std::string name="", std::string description="" );
59 60 61 62 63 64

    /**
     * Destructor.
     */
    virtual ~WModuleConnector();

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
65
    /**
66 67 68
     * Disconnects this connector if connected. If it is not connected: nothing happens.
     *
     * \param con the connector to disconnect.
69
     * \param removeFromOwnList if true the specified connection is also removed from the own connection list. If false it won't.
70
     */
71
    virtual void disconnect( boost::shared_ptr<WModuleConnector> con, bool removeFromOwnList = true );
72

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
73
    /**
74 75 76 77
     * Disconnects ALL connected connectors.
     */
    virtual void disconnectAll();

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
78
    /**
79 80
     * Connects this Module Connector with another one. During connection process, just the connectibility flag from
     * WModuleConnector::connectable is used to determine whether the connection is possible or not.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
81
     *
82
     * \param con the connector to connect.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
83
     *
84 85 86 87 88 89
     * \exception WModuleConnectionFailed if connection can not be established.
     *
     * \return true if successful
     */
    virtual void connect( boost::shared_ptr<WModuleConnector> con );

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
90
    /**
91 92
     * Checks whether this connector is connected to the given one. If there is the strange case where one connector is connected
     * with the other one but not vice versa it will throw an exception.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
93
     *
94
     * \param con the connector to check connection with.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
95
     *
96 97 98 99 100 101
     * \return true if connected
     *
     * \throw WModuleConnectionInvalid thrown if one connector thinks it is connected but the other one not.
     */
    bool isConnectedTo( boost::shared_ptr<WModuleConnector> con );

102 103 104 105 106 107 108
    /**
     * Gets the count of connections currently established.
     *
     * \return the number of connections.
     */
    unsigned int isConnected();

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
109
    /**
110
     * Connects a specified notify function with a signal this module instance is offering.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
111
     *
112 113 114 115 116 117 118
     * \exception WModuleSignalSubscriptionFailed thrown if the signal can't be connected.
     *
     * \param signal the signal to connect to.
     * \param notifier the notifier function to bind.
     *
     * \return connection descriptor.
     */
119
    virtual boost::signals2::connection subscribeSignal( MODULE_CONNECTOR_SIGNAL signal, t_GenericSignalHandlerType notifier );
120

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
121
    /**
122
     * Gives information about this connection.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
123
     *
124 125 126 127
     * \return The connection's description.
     */
    const std::string getDescription() const;

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
128
    /**
129
     * Sets the connector's description. This is not thread-safe! Do not use it outside the WModule thread.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
130
     *
131 132 133 134
     * \param desc the new description.
     */
    void setDescription( std::string desc );

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
135
    /**
136
     * Gives name of connection.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
137
     *
138
     * \return The name of this connection
139
     */
140 141
    const std::string getName() const;

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
142
    /**
143 144
     * Gives canonical name of connection. The canonical name is a descriptor including module name. The description is
     * ModuleName:ConnectorName.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
145
     *
146 147 148 149
     * \return The name of this connection
     */
    const std::string getCanonicalName() const;

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
150
    /**
151
     * Sets the connector's name. This is not thread-safe! Do not use it outside the WModule thread.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
152
     *
153 154 155
     * \param name the new name.
     */
    void setName( std::string name );
156

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
157
    /**
158
     * Checks whether the specified connector is connectable to this one.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
159
     *
160
     * \param con the connector to check against.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
161
     *
162 163 164 165
     * \return true if compatible.
     */
    virtual bool connectable( boost::shared_ptr<WModuleConnector> con )=0;

166 167
protected:

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
168
    /**
169 170
     * List of connectors connected to this connector.
     */
171
    std::set<boost::shared_ptr<WModuleConnector> > m_connected;
172

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
173
    /**
174 175 176
     * Lock for avoiding concurrent write to m_Connected (multiple reader, single writer lock). The read lock can be acquired using
     * the boost::shared_lock<boost::shared_mutex> lock( m_ConnectionListLock );.
     */
177
    boost::shared_mutex m_connectionListLock;
178

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
179
    /**
180
     * Connect additional signals.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
181
     *
182
     * \param con the connector that requests connection.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
183
     *
184 185
     */
    virtual void connectSignals( boost::shared_ptr<WModuleConnector> con );
186

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
187
    /**
188
     * Disconnect all signals subscribed by this connector from "con".
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
189
     *
190 191 192 193 194 195 196 197
     * \param con the connector that gets disconnected.
     */
    virtual void disconnectSignals( boost::shared_ptr<WModuleConnector> con );

    /**
     * Gives the signal handler function responsible for a given signal. Modules defining own signal handlers should overwrite
     * this function. This function is protected since boost::functions are callable, which is what is not wanted here. Just
     * signals should call them.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
198
     *
199
     * \param signal the signal to get the handler for.
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
200
     *
201 202 203 204
     * \return the signal handler for "signal".
     */
    virtual const t_GenericSignalHandlerType getSignalHandler( MODULE_CONNECTOR_SIGNAL signal );

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
205
    /**
206
     * The Module this connector belongs to
207
     */
Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
208
    boost::shared_ptr< WModule > m_module;
209

210 211 212 213 214
    /**
     * The name of the module owning this connector.
     */
    std::string m_moduleName;

215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
    /**
     * Gets called whenever a connector gets connected to the specified input.
     *
     * \param here the connector of THIS module that got connected to "there"
     * \param there the connector that has been connected with the connector "here" of this module.
     */
    virtual void notifyConnectionEstablished( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there );

    /**
     * Gets called whenever a connection between a remote and local connector gets closed.
     *
     * \param here the connector of THIS module getting disconnected.
     * \param there the connector of the other module getting disconnected.
     */
    virtual void notifyConnectionClosed( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there );

231
private:
232

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
233
    /**
234 235
     * The connections name.
     */
236
    std::string m_name;
237

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
238
    /**
239 240
     * The connections description.
     */
241
    std::string m_description;
242

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
243
    /**
244 245 246 247
     * Signal emitted whenever connection has been established.
     */
    t_GenericSignalType signal_ConnectionEstablished;

Sebastian Eichelbaum's avatar
[STYLE]  
Sebastian Eichelbaum committed
248
    /**
249 250 251
     * Signal emitted whenever connection has been closed.
     */
    t_GenericSignalType signal_ConnectionClosed;
252 253 254 255
};

#endif  // WMODULECONNECTOR_H