OpenWalnut  1.4.0
WModule.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 WMODULE_H
00026 #define WMODULE_H
00027 
00028 #include <string>
00029 #include <typeinfo>
00030 #include <vector>
00031 
00032 #include <boost/enable_shared_from_this.hpp>
00033 #include <boost/filesystem.hpp>
00034 #include <boost/function.hpp>
00035 #include <boost/shared_ptr.hpp>
00036 #include <boost/signals2/signal.hpp>
00037 #include <boost/thread.hpp>
00038 
00039 #include "../common/WConditionSet.h"
00040 #include "../common/WLogger.h"
00041 #include "../common/WProgress.h"
00042 #include "../common/WProgressCombiner.h"
00043 #include "../common/WProperties.h"
00044 #include "../common/WPrototyped.h"
00045 #include "../common/WRequirement.h"
00046 #include "../common/WThreadedRunner.h"
00047 #include "../dataHandler/WDataSet.h"
00048 #include "../dataHandler/WDataSetSingle.h"
00049 #include "../dataHandler/WValueSet.h"
00050 
00051 #include "WModuleCombinerTypes.h"
00052 #include "WModuleConnectorSignals.h"
00053 #include "WModuleSignals.h"
00054 #include "WModuleTypes.h"
00055 #include "WModuleMetaInformation.h"
00056 
00057 class WModuleConnector;
00058 class WModuleContainer;
00059 class WModuleFactory;
00060 class WModuleLoader;
00061 class WModuleInputConnector;
00062 class WModuleOutputConnector;
00063 template < typename T > class WModuleInputData;
00064 template < typename T > class WModuleInputForwardData;
00065 template < typename T > class WModuleOutputData;
00066 
00067 /**
00068  * Class representing a single module of OpenWalnut.
00069  * \ingroup kernel
00070  */
00071 class  WModule: public WThreadedRunner,
00072                                public WPrototyped,
00073                                public boost::enable_shared_from_this< WModule >
00074 {
00075 friend class WModuleConnector;  // requires access to notify members
00076 template< typename T > friend class WModuleInputData;  // requires access for convenience functions to automatically add a created connector
00077 template< typename T > friend class WModuleInputForwardData;  // requires access for convenience functions to automatically add a created connector
00078 template< typename T > friend class WModuleOutputData;  // requires access for convenience functions to automatically add a created connector
00079 template< typename T > friend class WModuleOutputForwardData;  // requires access for convenience functions to automatically add a created connector
00080 friend class WModuleFactory;    // for proper creation of module instances, the factory needs access to protected functions.
00081                                 // (especially initialize)
00082 friend class WModuleContainer;  // for proper management of m_container WModuleContainer needs access.
00083 friend class WModuleLoader;     // needs to set several protected values like local path and library names.
00084 
00085 public:
00086     /**
00087      * Constructs a new WModule instance
00088      */
00089     WModule();
00090 
00091     /**
00092      * Destructor.
00093      */
00094     virtual ~WModule();
00095 
00096     /**
00097      * The type for the list of input connectors.
00098      */
00099     typedef std::vector< boost::shared_ptr< WModuleInputConnector > > InputConnectorList;
00100 
00101     /**
00102      * The type for the list of output connectors.
00103      */
00104     typedef std::vector< boost::shared_ptr< WModuleOutputConnector > > OutputConnectorList;
00105 
00106     /**
00107      * Shared pointer to a WModule.
00108      */
00109     typedef boost::shared_ptr< WModule > SPtr;
00110 
00111     /**
00112      * Shared pointer to a const WModule.
00113      */
00114     typedef boost::shared_ptr< const WModule > ConstSPtr;
00115 
00116     /**
00117      * Gives back input connectors.
00118      *
00119      * \return the input connectors.
00120      */
00121     const InputConnectorList& getInputConnectors() const;
00122 
00123     /**
00124      * Finds the named connector for the module.
00125      *
00126      * \param name the name. This can be a canonical name or the connector name.
00127      *
00128      * \return the connector.
00129      * \throw WModuleConnectorNotFound thrown whenever the module does not provide the specified connector.
00130      */
00131     boost::shared_ptr< WModuleInputConnector > getInputConnector( std::string name );
00132 
00133     /**
00134      * Finds the named connector for the module. This is similar to getInputConnector but it does not throw an exception if the connector could
00135      * not be found.
00136      *
00137      * \param name the name. This can be a canonical name or the connector name.
00138      *
00139      * \return the connector or NULL if not found
00140      */
00141     boost::shared_ptr< WModuleInputConnector > findInputConnector( std::string name );
00142 
00143     /**
00144      * Gives back output connectors.
00145      *
00146      * \return the output connectors.
00147      */
00148     const OutputConnectorList& getOutputConnectors() const;
00149 
00150     /**
00151      * Finds the named connector for the module.
00152      *
00153      * \param name the name. This can be a canonical name or the connector name.
00154      *
00155      * \return the connector.
00156      * \throw WModuleConnectorNotFound thrown whenever the module does not provide the specified connector.
00157      */
00158     boost::shared_ptr< WModuleOutputConnector > getOutputConnector( std::string name );
00159 
00160     /**
00161      * Finds the named connector for the module. This is similar to getOutputConnector but it does not throw an exception if the connector could
00162      * not be found.
00163      *
00164      * \param name the name. This can be a canonical name or the connector name.
00165      *
00166      * \return the connector or NULL if not found.
00167      */
00168     boost::shared_ptr< WModuleOutputConnector > findOutputConnector( std::string name );
00169 
00170     /**
00171      * Finds the named connector for the module. This searches for inputs and outputs.
00172      *
00173      * \param name the name. This can be a canonical name or the connector name.
00174      *
00175      * \return the connector.
00176      * \throw WModuleConnectorNotFound thrown whenever the module does not provide the specified connector.
00177      */
00178     boost::shared_ptr< WModuleConnector > getConnector( std::string name );
00179 
00180     /**
00181      * Finds the named connector for the module. This searches for inputs and outputs. This is similar to getConnector but it does not throw an
00182      * exception if the connector could not be found.
00183      *
00184      * \param name the name. This can be a canonical name or the connector name.
00185      *
00186      * \return the connector or NULL if not found.
00187      */
00188     boost::shared_ptr< WModuleConnector > findConnector( std::string name );
00189 
00190     /**
00191      * Return a pointer to the properties object of the module.
00192      *
00193      * \return the properties.
00194      */
00195     boost::shared_ptr< WProperties > getProperties() const;
00196 
00197     /**
00198      * Return a pointer to the information properties object of the module. The module intends these properties to not be modified.
00199      *
00200      * \return the properties.
00201      */
00202     boost::shared_ptr< WProperties > getInformationProperties() const;
00203 
00204     /**
00205      * Determines whether the module instance is properly initialized.
00206      *
00207      * \return true if properly initialized.
00208      */
00209     const WBoolFlag& isInitialized() const;
00210 
00211     /**
00212      * Checks whether the module instance is ready to be used. This is the case if isInitialized && isAssociated.
00213      *
00214      * \return isInitialized && isAssociated
00215      */
00216     const WBoolFlag&  isUseable() const;
00217 
00218      /**
00219       * Checks whether this module is associated with an container.
00220       *
00221       * \return true if associated.
00222       */
00223     const WBoolFlag&  isAssociated() const;
00224 
00225      /**
00226       * Checks whether this module is ready.
00227       *
00228       * \return true if ready.
00229       */
00230     const WBoolFlag&  isReady() const;
00231 
00232     /**
00233      * This is the logical or of isReady and isCrashed. You should use this condition if you need to wait for a module to get ready. If it
00234      * crashed before ready() got called, you most probably would wait endlessly.
00235      *
00236      * \return isReady || isCrashed.
00237      */
00238     const WBoolFlag& isReadyOrCrashed() const;
00239 
00240     /**
00241      * Returns a flag denoting whether the thread currently is running or nor. It is also useful to get a callback whenever a module stops.
00242      *
00243      * \return the flag
00244      */
00245     const WBoolFlag& isRunning() const;
00246 
00247     /**
00248      * This method waits for the module to be restored completely. Use this instead of m_isLoadFinished->wait() as this is not properly defined
00249      * when adding modules without using the project file loader.
00250      *
00251      * \note you have to use this after your \ref ready call (or it will cause a freeze)
00252      */
00253     void waitRestored();
00254 
00255     /**
00256      * Check whether this module is in restore mode. This means that some loader is currently handling the module. You are allowed to ignore this
00257      * flag. But be aware that the loader can set connections and properties even if you do not expect this.
00258      *
00259      * \return true if the module is currently being restored.
00260      */
00261     bool isRestoreNeeded() const;
00262 
00263     /**
00264      * Change the restore mode. \see isRestoreNeeded for details.
00265      *
00266      * \note loaders need to set this flag before the module is associated with a container.
00267      *
00268      * \param restore the mode.
00269      */
00270     void setRestoreNeeded( bool restore = true );
00271 
00272     /**
00273      * Called by loaders to tell the module that loading has been completed.
00274      */
00275     void reportRestoreComplete();
00276 
00277     /**
00278      * The container this module is associated with.
00279      *
00280      * \return the container.
00281     */
00282     boost::shared_ptr< WModuleContainer > getAssociatedContainer() const;
00283 
00284     /**
00285      * Due to the prototype design pattern used to build modules, this method returns a new instance of this module. NOTE: it
00286      * should never be initialized or modified in some other way.
00287      *
00288      * \return the prototype used to create every module in OpenWalnut.
00289      */
00290     virtual boost::shared_ptr< WModule > factory() const = 0;
00291 
00292     /**
00293      * Connects a specified notify function with a signal this module instance is offering.
00294      *
00295      * \exception WModuleSignalSubscriptionFailed thrown if the signal can't be connected.
00296      *
00297      * \param signal the signal to connect to.
00298      * \param notifier the notifier function to bind.
00299      *
00300      * \return connection descriptor.
00301      */
00302     virtual boost::signals2::connection subscribeSignal( MODULE_SIGNAL signal, t_ModuleGenericSignalHandlerType notifier );
00303 
00304     /**
00305      * Connects a specified notify function with a signal this module instance is offering. Please note that there also is a
00306      * WThreadedRunner::subscribeSignal which allows error callbacks. The difference to this one is that the WThreadedRunner's version does not
00307      * provide the sender information (shared_ptr).
00308      *
00309      * \exception WModuleSignalSubscriptionFailed thrown if the signal can't be connected.
00310      *
00311      * \param signal the signal to connect to.
00312      * \param notifier the notifier function to bind.
00313      *
00314      * \return connection descriptor.
00315      */
00316     virtual boost::signals2::connection subscribeSignal( MODULE_SIGNAL signal, t_ModuleErrorSignalHandlerType notifier );
00317 
00318     /**
00319      * Gets the modules base progress. This is actually a progress combiner, which bundles all progresses.
00320      *
00321      * \return the progress combiner for this module.
00322      */
00323     virtual boost::shared_ptr< WProgressCombiner > getRootProgressCombiner();
00324 
00325     /**
00326      * Get the icon for this module in XPM format.
00327      * \return The icon.
00328      */
00329     virtual const char** getXPMIcon() const;
00330 
00331     /**
00332      * Gets the type of the module. This is useful for FAST differentiation between several modules like standard modules and data
00333      * modules which play a special role in OpenWalnut/Kernel.
00334      *
00335      * \return the Type. If you do not overwrite this method, it will return MODULE_ARBITRARY.
00336      */
00337     virtual MODULE_TYPE getType() const;
00338 
00339     /**
00340      * Completely disconnects all connected connectors of this module. This is useful to isolate a module (for deletion, removal from a container
00341      * and so on.)
00342      */
00343     void disconnect();
00344 
00345     /**
00346      * Gives a list of all WDisconnectCombiners possible. Please note that while the list exists, connections might change.
00347      *
00348      * \return the list of possible disconnect operations
00349      */
00350     WCombinerTypes::WDisconnectList getPossibleDisconnections();
00351 
00352     /**
00353      * Returns the local path of the module. Whenever you try to load local resources, use this path. It is especially useful for shader loading.
00354      *
00355      * \return the local module path.
00356      */
00357     boost::filesystem::path getLocalPath() const;
00358 
00359     /**
00360      * Returns the absolute path to the library containing this module.
00361      *
00362      * \return the path.
00363      */
00364     boost::filesystem::path getLibPath() const;
00365 
00366     /**
00367      * Returns the name of the package the module belongs to, The package name basically is the name of the
00368      * library containing this and maybe other modules. Your build system manages this. The package name is used to identify the resources for
00369      * the modules in the library (a.k.a package).
00370      *
00371      * \return the name
00372      */
00373     std::string getPackageName() const;
00374 
00375     /**
00376      * Checks whether the module was marked as deprecated.
00377      *
00378      * \return true if deprecated
00379      */
00380     bool isDeprecated() const;
00381 
00382     /**
00383      * Queries the deprecation message of a module if specified. If not specified, an empty string is returned. Check \ref isDeprecated first.
00384      *
00385      * \return deprecation message
00386      */
00387     std::string getDeprecationMessage() const;
00388 
00389     /**
00390      * The meta information of this module. This contains several information like name, description, icons, help links and so on. It, at least,
00391      * contains the name.
00392      *
00393      * \return the meta info object for this module.
00394      */
00395     virtual WModuleMetaInformation::ConstSPtr getMetaInformation() const;
00396 
00397     /**
00398      * Get the UUID of the module instance. Use this when you need to guarantee a unique instance name, even across multiple OW sessions. The
00399      * UUID gets set by the initialize method once and can never be changed.
00400      *
00401      * \return the UUID as string.
00402      */
00403     const std::string& getUUID() const;
00404 
00405     /**
00406      * Find a module instance by UUID.
00407      *
00408      * \param uuid the uuid to search for.
00409      *
00410      * \return the module, or NULL if not found
00411      */
00412     static SPtr findByUUID( std::string uuid );
00413 
00414 protected:
00415     /**
00416      * Entry point after loading the module. Runs in separate thread.
00417      */
00418     virtual void moduleMain() = 0;
00419 
00420     /**
00421      * Thread entry point. Calls moduleMain and sends error notification if needed.
00422      */
00423     void threadMain();
00424 
00425     /**
00426      * This method is called if an exception was caught, which came from the custom thread code. This method is virtual and allows you to
00427      * overwrite the default behaviour. If you overwrite this method, you should call \ref WThreadedRunner::handleDeadlyException or
00428      * WThreadedRunner::onThreadException if you are finished with your customized code.
00429      *
00430      * \param e the exception that was caught.
00431      */
00432     virtual void onThreadException( const WException& e );
00433 
00434      /**
00435       * Sets the container this module is associated with.
00436       *
00437       * \param container the container to associate with.
00438       */
00439     void setAssociatedContainer( boost::shared_ptr< WModuleContainer > container );
00440 
00441     // **************************************************************************************************************************
00442     //
00443     // Connector Management
00444     //
00445     // **************************************************************************************************************************
00446 
00447     /**
00448      * Initialize connectors in this function. This function must not be called multiple times for one module instance.
00449      * The module container manages calling those functions -> so just implement it.
00450      */
00451     virtual void connectors();
00452 
00453     /**
00454      * Initialize properties in this function. This function must not be called multiple times for one module instance.
00455      * The module container manages calling those functions -> so just implement it. Once initialized the number and type
00456      * of all properties should be set.
00457      */
00458     virtual void properties();
00459 
00460     /**
00461      * Initialize requirements in this function. This function must not be called multiple times for one module instance.
00462      * The module should always implement this. Using this method, a module can tell the kernel what it needs to run properly. For example, it
00463      * can require a running graphics engine or, in the case of module containers, other modules.
00464      */
00465     virtual void requirements();
00466 
00467     /**
00468      * This function allows module programmers to mark their modules deprecated in a user-friendly way. If you implement this function, you need
00469      * to specify an text which should mention an alternative module.
00470      *
00471      * \note do not add sentences like "this module is deprecated" or similar, since the GUI the user is using already shows this message. The
00472      * message should say WHY it is deprecated and what alternative module is available.
00473      * \return deprecation message
00474      */
00475     virtual std::string deprecated() const;
00476 
00477     /**
00478      * Manages initialization. Gets called by module container and ensures all properties, requirements, and connectors are properly set up.
00479      *
00480      * \throw WModuleConnectorInitFailed if called multiple times.
00481      */
00482     void initialize();
00483 
00484     /**
00485      * Called whenever the module should shutdown.
00486      */
00487     virtual void cleanup();
00488 
00489     /**
00490      * Adds the specified connector to the list of inputs.
00491      *
00492      * \param con the connector.
00493      */
00494     void addConnector( boost::shared_ptr<WModuleInputConnector> con );
00495 
00496     /**
00497      * Adds the specified connector to the list of outputs.
00498      *
00499      * \param con the connector.
00500      */
00501     void addConnector( boost::shared_ptr<WModuleOutputConnector> con );
00502 
00503     /**
00504      * Removes all connectors properly. It disconnects the connectors and cleans the connectors list.
00505      */
00506     void removeConnectors();
00507 
00508     /**
00509      * Callback for m_active. Overwrite this in your modules to handle m_active changes separately.
00510      */
00511     virtual void activate();
00512 
00513     // **************************************************************************************************************************
00514     //
00515     // Signal handlers that HAVE to be in every module. By default they do nothing. You should overwrite them to get notified
00516     // with the corresponding signal
00517     //
00518     // **************************************************************************************************************************
00519 
00520     /**
00521      * Gives the signal handler function responsible for a given signal. Modules defining own signal handlers should overwrite
00522      * this function. This function is protected since boost::functions are callable, which is what is not wanted here. Just
00523      * signals should call them.
00524      *
00525      * \param signal the signal to get the handler for.
00526      *
00527      * \return the signal handler for "signal".
00528      */
00529     virtual const t_GenericSignalHandlerType getSignalHandler( MODULE_CONNECTOR_SIGNAL signal );
00530 
00531     /**
00532      * Gets called whenever a connector gets connected to the specified input.
00533      *
00534      * \param here the connector of THIS module that got connected to "there"
00535      * \param there the connector that has been connected with the connector "here" of this module.
00536      */
00537     virtual void notifyConnectionEstablished( boost::shared_ptr<WModuleConnector> here,
00538                                               boost::shared_ptr<WModuleConnector> there );
00539     /**
00540      * Gets called whenever a connection between a remote and local connector gets closed.
00541      *
00542      * \param here the connector of THIS module getting disconnected.
00543      * \param there the connector of the other module getting disconnected.
00544      */
00545     virtual void notifyConnectionClosed( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there );
00546 
00547     /**
00548      * Gets called when the data on one input connector changed.
00549      *
00550      * \param input the input connector receiving the change.
00551      * \param output the output connector sending the change notification.
00552      */
00553     virtual void notifyDataChange( boost::shared_ptr<WModuleConnector> input,
00554                                    boost::shared_ptr<WModuleConnector> output );
00555 
00556     /**
00557      * Call this whenever your module is ready and can react on property changes.
00558      */
00559     void ready();
00560 
00561     /**
00562      * Logger instance for comfortable info logging. Simply use logInfo() << "my info".
00563      *
00564      * \return the logger stream.
00565      */
00566     wlog::WStreamedLogger infoLog() const;
00567 
00568     /**
00569      * Logger instance for comfortable debug logging. Simply use logDebug() << "my debug".
00570      *
00571      * \return the logger stream.
00572      */
00573     wlog::WStreamedLogger debugLog() const;
00574 
00575     /**
00576      * Logger instance for comfortable warning- logs. Simply use logWarning() << "my warning".
00577      *
00578      * \return the logger stream.
00579      */
00580     wlog::WStreamedLogger warnLog() const;
00581 
00582     /**
00583      * Logger instance for comfortable error logging. Simply use logError() << "my error".
00584      *
00585      * \return the logger stream.
00586      */
00587     wlog::WStreamedLogger errorLog() const;
00588 
00589     // **************************************************************************************************************************
00590     //
00591     // Loading Management
00592     //
00593     // **************************************************************************************************************************
00594 
00595     /**
00596      * Sets the local module path. This gets called by the module loader.
00597      *
00598      * \param path the local path.
00599      */
00600     void setLocalPath( boost::filesystem::path path );
00601 
00602     /**
00603      * Set the path to the library which contains this module. This is usually set by \ref WModuleLoader.
00604      *
00605      * \param path the path to the library. Needs to be absolute.
00606      */
00607     void setLibPath( boost::filesystem::path path );
00608 
00609     /**
00610      * Set the package name. This basically is the library name of the lib containing this module. The package name is used to identify resources
00611      * and other things which belong to a library (a.k.a. package).
00612      *
00613      * \param name the name to set
00614      */
00615     void setPackageName( std::string name );
00616 
00617     // **************************************************************************************************************************
00618     //
00619     // Members
00620     //
00621     // **************************************************************************************************************************
00622 
00623     /**
00624      * The property object for the module.
00625      */
00626     boost::shared_ptr< WProperties > m_properties;
00627 
00628     /**
00629      * The property object for the module containing only module whose purpose is "PV_PURPOSE_INFORMNATION". It is useful to define some property
00630      * to only be of informational nature. The GUI does not modify them. As it is a WProperties instance, you can use it the same way as
00631      * m_properties.
00632      */
00633     boost::shared_ptr< WProperties > m_infoProperties;
00634 
00635     /**
00636      * Progress indicator used as parent for all progress' of this module.
00637      */
00638     boost::shared_ptr< WProgressCombiner > m_progress;
00639 
00640     /**
00641      * True if everything is initialized and ready to be used.
00642      */
00643     WBoolFlag m_initialized;
00644 
00645     /**
00646      * True if container got associated with this flag.
00647      */
00648     WBoolFlag m_isAssociated;
00649 
00650     /**
00651      * True if associated && initialized.
00652      */
00653     WBoolFlag m_isUsable;
00654 
00655     /**
00656      * True if ready() was called.
00657      */
00658     WBoolFlag m_isReady;
00659 
00660     /**
00661      * It is true whenever m_isReady or WThreadedRunner::m_isCrashed is true. This is mostly useful for functions
00662      * which need to wait for a module to get ready.
00663      */
00664     WBoolFlag m_isReadyOrCrashed;
00665 
00666     /**
00667      * True if the module currently is running.
00668      */
00669     WBoolFlag m_isRunning;
00670 
00671     /**
00672      * Flag to denote whether the module container and the project loader have finished their work. \see isLoadFinished.
00673      */
00674     WBoolFlag m_isLoadFinished;
00675 
00676     /**
00677      * Flag denoting the current restore mode. \see setRestoreNeeded
00678      */
00679     bool m_restoreMode;
00680 
00681     /**
00682      * Progress indicator for the "ready" state.
00683      */
00684     boost::shared_ptr< WProgress > m_readyProgress;
00685 
00686     /**
00687      * The internal state of the module. This is, by default, simply the exit flag from WThreadedRunner.
00688      */
00689     WConditionSet m_moduleState;
00690 
00691     /**
00692      * The container this module belongs to.
00693      */
00694     boost::shared_ptr< WModuleContainer > m_container;
00695 
00696     /**
00697      * Set of input connectors associated with this module.
00698      */
00699     InputConnectorList m_inputConnectors;
00700 
00701     /**
00702      * Set of output connectors associated with this module.
00703      */
00704     OutputConnectorList m_outputConnectors;
00705 
00706     /**
00707      * True whenever the module should be active
00708      */
00709     WPropBool m_active;
00710 
00711     /**
00712      * This property holds a user specified name for the current module instance.
00713      */
00714     WPropString m_runtimeName;
00715 
00716     /**
00717      * The path where the module binary resides in. This path should be used whenever the module needs to load resources. It gets set by the
00718      * module loader. Use this to load shaders and so on.
00719      */
00720     boost::filesystem::path m_localPath;
00721 
00722     /**
00723      * The absolute path to the library containing this module.
00724      */
00725     boost::filesystem::path m_libPath;
00726 
00727     /**
00728      * The name of the lib/the package containing this module.
00729      */
00730     std::string m_packageName;
00731 
00732     /**
00733      * The type of the requirement list.
00734      */
00735     typedef std::vector< WRequirement* > Requirements;
00736 
00737     /**
00738      * The list of requirements.
00739      */
00740     Requirements m_requirements;
00741 
00742 private:
00743      /**
00744      * Lock for m_inputConnectors.
00745      */
00746     // boost::shared_mutex m_inputConnectorsLock;
00747 
00748     /**
00749      * Lock for m_outputConnectors.
00750      */
00751     // boost::shared_mutex m_outputConnectorsLock;
00752 
00753     /**
00754      * Module meta information. Set by the factory creating the module instance.
00755      */
00756     WModuleMetaInformation::SPtr m_meta;
00757 
00758     /**
00759      * Signal fired whenever a module main thread is ready.
00760      */
00761     t_ModuleGenericSignalType signal_ready;
00762 
00763     /**
00764      * Signal fired whenever a module main thread throws an exception/error.
00765      */
00766     t_ModuleErrorSignalType signal_error;
00767 
00768     /**
00769      * This method checks whether all the requirements of the module are complied.
00770      *
00771      * \return the requirement that has failed.
00772      */
00773     const WRequirement* checkRequirements() const;
00774 
00775     /**
00776      * The unique ID of the module instance.
00777      */
00778     std::string m_uuid;
00779 
00780     /**
00781      * Set a uuid. If the specified string is empty, a new one gets created.
00782      *
00783      * \param uuid the uuid to set.
00784      */
00785     void setUUID( std::string uuid );
00786 };
00787 
00788 /**
00789  * Simply a list of modules. The type is used by the following macros and typedefs
00790  */
00791 typedef std::vector< boost::shared_ptr< WModule > > WModuleList;
00792 
00793 /**
00794  * The signature used for the module loading entry point
00795  */
00796 typedef void ( *W_LOADABLE_MODULE_SIGNATURE )( WModuleList& );
00797 
00798 /**
00799  * The signature used for the loaded toolbox as arbitrary registration function.
00800  */
00801 typedef void ( *W_LOADABLE_REGISTERARBITRARY_SIGNATURE )( const boost::filesystem::path& );
00802 
00803 /**
00804  * The following macro is used by modules so the factory can acquire a prototype instance from a shared library using the symbol.
00805  * You can write this symbol for your own if you need to add multiple modules to the list. This one is for convenience.
00806  *
00807  * \note we need the module instance to be created using a shared_ptr as WModule is derived from enable_shared_from_this. Removing the shared
00808  *       pointer causes segmentation faults during load.
00809  */
00810 #define W_LOADABLE_MODULE( MODULECLASS ) \
00811 extern "C"                       void WLoadModule( WModuleList& m ) { m.push_back( boost::shared_ptr< WModule >( new MODULECLASS ) ); }  // NOLINT
00812 
00813 /**
00814  * The corresponding symbol name.
00815  */
00816 #define W_LOADABLE_MODULE_SYMBOL "WLoadModule"
00817 
00818 /**
00819  * THe register function's symbol name.
00820  */
00821 #define W_LOADABLE_REGISTERARBITRARY_SYMBOL "WRegisterArbitrary"
00822 
00823 /**
00824  * \defgroup modules Modules
00825  *
00826  * \brief
00827  * This group contains modules of OpenWalnut.
00828  * The term modules can be understood as "plugin" or "algorithm" in this context.
00829  */
00830 #endif  // WMODULE_H
00831