OpenWalnut  1.4.0
WModule.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WMODULE_H
26 #define WMODULE_H
27 
28 #include <string>
29 #include <typeinfo>
30 #include <vector>
31 
32 #ifndef Q_MOC_RUN
33 #include <boost/enable_shared_from_this.hpp>
34 #endif
35 #ifndef Q_MOC_RUN
36 #include <boost/filesystem.hpp>
37 #endif
38 #ifndef Q_MOC_RUN
39 #include <boost/function.hpp>
40 #endif
41 #ifndef Q_MOC_RUN
42 #include <boost/shared_ptr.hpp>
43 #endif
44 #ifndef Q_MOC_RUN
45 #include <boost/signals2/signal.hpp>
46 #endif
47 #ifndef Q_MOC_RUN
48 #include <boost/thread.hpp>
49 #endif
50 
51 #include "../common/WConditionSet.h"
52 #include "../common/WLogger.h"
53 #include "../common/WProgress.h"
54 #include "../common/WProgressCombiner.h"
55 #include "../common/WProperties.h"
56 #include "../common/WPrototyped.h"
57 #include "../common/WRequirement.h"
58 #include "../common/WThreadedRunner.h"
59 #include "../dataHandler/WDataSet.h"
60 #include "../dataHandler/WDataSetSingle.h"
61 #include "../dataHandler/WValueSet.h"
62 
63 #include "WModuleCombinerTypes.h"
64 #include "WModuleConnectorSignals.h"
65 #include "WModuleSignals.h"
66 #include "WModuleTypes.h"
67 #include "WModuleMetaInformation.h"
68 
69 class WModuleConnector;
70 class WModuleContainer;
71 class WModuleFactory;
72 class WModuleLoader;
75 template < typename T > class WModuleInputData;
76 template < typename T > class WModuleInputForwardData;
77 template < typename T > class WModuleOutputData;
78 
79 /**
80  * Class representing a single module of OpenWalnut.
81  * \ingroup kernel
82  */
83 class WModule: public WThreadedRunner,
84  public WPrototyped,
85  public boost::enable_shared_from_this< WModule >
86 {
87 friend class WModuleConnector; // requires access to notify members
88 template< typename T > friend class WModuleInputData; // requires access for convenience functions to automatically add a created connector
89 template< typename T > friend class WModuleInputForwardData; // requires access for convenience functions to automatically add a created connector
90 template< typename T > friend class WModuleOutputData; // requires access for convenience functions to automatically add a created connector
91 template< typename T > friend class WModuleOutputForwardData; // requires access for convenience functions to automatically add a created connector
92 friend class WModuleFactory; // for proper creation of module instances, the factory needs access to protected functions.
93  // (especially initialize)
94 friend class WModuleContainer; // for proper management of m_container WModuleContainer needs access.
95 friend class WModuleLoader; // needs to set several protected values like local path and library names.
96 
97 public:
98  /**
99  * Constructs a new WModule instance
100  */
101  WModule();
102 
103  /**
104  * Destructor.
105  */
106  virtual ~WModule();
107 
108  /**
109  * The type for the list of input connectors.
110  */
111  typedef std::vector< boost::shared_ptr< WModuleInputConnector > > InputConnectorList;
112 
113  /**
114  * The type for the list of output connectors.
115  */
116  typedef std::vector< boost::shared_ptr< WModuleOutputConnector > > OutputConnectorList;
117 
118  /**
119  * Shared pointer to a WModule.
120  */
121  typedef boost::shared_ptr< WModule > SPtr;
122 
123  /**
124  * Shared pointer to a const WModule.
125  */
126  typedef boost::shared_ptr< const WModule > ConstSPtr;
127 
128  /**
129  * Gives back input connectors.
130  *
131  * \return the input connectors.
132  */
133  const InputConnectorList& getInputConnectors() const;
134 
135  /**
136  * Finds the named connector for the module.
137  *
138  * \param name the name. This can be a canonical name or the connector name.
139  *
140  * \return the connector.
141  * \throw WModuleConnectorNotFound thrown whenever the module does not provide the specified connector.
142  */
143  boost::shared_ptr< WModuleInputConnector > getInputConnector( std::string name );
144 
145  /**
146  * Finds the named connector for the module. This is similar to getInputConnector but it does not throw an exception if the connector could
147  * not be found.
148  *
149  * \param name the name. This can be a canonical name or the connector name.
150  *
151  * \return the connector or NULL if not found
152  */
153  boost::shared_ptr< WModuleInputConnector > findInputConnector( std::string name );
154 
155  /**
156  * Gives back output connectors.
157  *
158  * \return the output connectors.
159  */
160  const OutputConnectorList& getOutputConnectors() const;
161 
162  /**
163  * Finds the named connector for the module.
164  *
165  * \param name the name. This can be a canonical name or the connector name.
166  *
167  * \return the connector.
168  * \throw WModuleConnectorNotFound thrown whenever the module does not provide the specified connector.
169  */
170  boost::shared_ptr< WModuleOutputConnector > getOutputConnector( std::string name );
171 
172  /**
173  * Finds the named connector for the module. This is similar to getOutputConnector but it does not throw an exception if the connector could
174  * not be found.
175  *
176  * \param name the name. This can be a canonical name or the connector name.
177  *
178  * \return the connector or NULL if not found.
179  */
180  boost::shared_ptr< WModuleOutputConnector > findOutputConnector( std::string name );
181 
182  /**
183  * Finds the named connector for the module. This searches for inputs and outputs.
184  *
185  * \param name the name. This can be a canonical name or the connector name.
186  *
187  * \return the connector.
188  * \throw WModuleConnectorNotFound thrown whenever the module does not provide the specified connector.
189  */
190  boost::shared_ptr< WModuleConnector > getConnector( std::string name );
191 
192  /**
193  * Finds the named connector for the module. This searches for inputs and outputs. This is similar to getConnector but it does not throw an
194  * exception if the connector could not be found.
195  *
196  * \param name the name. This can be a canonical name or the connector name.
197  *
198  * \return the connector or NULL if not found.
199  */
200  boost::shared_ptr< WModuleConnector > findConnector( std::string name );
201 
202  /**
203  * Return a pointer to the properties object of the module.
204  *
205  * \return the properties.
206  */
207  boost::shared_ptr< WProperties > getProperties() const;
208 
209  /**
210  * Return a pointer to the information properties object of the module. The module intends these properties to not be modified.
211  *
212  * \return the properties.
213  */
214  boost::shared_ptr< WProperties > getInformationProperties() const;
215 
216  /**
217  * Determines whether the module instance is properly initialized.
218  *
219  * \return true if properly initialized.
220  */
221  const WBoolFlag& isInitialized() const;
222 
223  /**
224  * Checks whether the module instance is ready to be used. This is the case if isInitialized && isAssociated.
225  *
226  * \return isInitialized && isAssociated
227  */
228  const WBoolFlag& isUseable() const;
229 
230  /**
231  * Checks whether this module is associated with an container.
232  *
233  * \return true if associated.
234  */
235  const WBoolFlag& isAssociated() const;
236 
237  /**
238  * Checks whether this module is ready.
239  *
240  * \return true if ready.
241  */
242  const WBoolFlag& isReady() const;
243 
244  /**
245  * 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
246  * crashed before ready() got called, you most probably would wait endlessly.
247  *
248  * \return isReady || isCrashed.
249  */
250  const WBoolFlag& isReadyOrCrashed() const;
251 
252  /**
253  * Returns a flag denoting whether the thread currently is running or nor. It is also useful to get a callback whenever a module stops.
254  *
255  * \return the flag
256  */
257  const WBoolFlag& isRunning() const;
258 
259  /**
260  * This method waits for the module to be restored completely. Use this instead of m_isLoadFinished->wait() as this is not properly defined
261  * when adding modules without using the project file loader.
262  *
263  * \note you have to use this after your \ref ready call (or it will cause a freeze)
264  */
265  void waitRestored();
266 
267  /**
268  * Check whether this module is in restore mode. This means that some loader is currently handling the module. You are allowed to ignore this
269  * flag. But be aware that the loader can set connections and properties even if you do not expect this.
270  *
271  * \return true if the module is currently being restored.
272  */
273  bool isRestoreNeeded() const;
274 
275  /**
276  * Change the restore mode. \see isRestoreNeeded for details.
277  *
278  * \note loaders need to set this flag before the module is associated with a container.
279  *
280  * \param restore the mode.
281  */
282  void setRestoreNeeded( bool restore = true );
283 
284  /**
285  * Called by loaders to tell the module that loading has been completed.
286  */
287  void reportRestoreComplete();
288 
289  /**
290  * The container this module is associated with.
291  *
292  * \return the container.
293  */
294  boost::shared_ptr< WModuleContainer > getAssociatedContainer() const;
295 
296  /**
297  * Due to the prototype design pattern used to build modules, this method returns a new instance of this module. NOTE: it
298  * should never be initialized or modified in some other way.
299  *
300  * \return the prototype used to create every module in OpenWalnut.
301  */
302  virtual boost::shared_ptr< WModule > factory() const = 0;
303 
304  /**
305  * Connects a specified notify function with a signal this module instance is offering.
306  *
307  * \exception WModuleSignalSubscriptionFailed thrown if the signal can't be connected.
308  *
309  * \param signal the signal to connect to.
310  * \param notifier the notifier function to bind.
311  *
312  * \return connection descriptor.
313  */
314  virtual boost::signals2::connection subscribeSignal( MODULE_SIGNAL signal, t_ModuleGenericSignalHandlerType notifier );
315 
316  /**
317  * Connects a specified notify function with a signal this module instance is offering. Please note that there also is a
318  * WThreadedRunner::subscribeSignal which allows error callbacks. The difference to this one is that the WThreadedRunner's version does not
319  * provide the sender information (shared_ptr).
320  *
321  * \exception WModuleSignalSubscriptionFailed thrown if the signal can't be connected.
322  *
323  * \param signal the signal to connect to.
324  * \param notifier the notifier function to bind.
325  *
326  * \return connection descriptor.
327  */
328  virtual boost::signals2::connection subscribeSignal( MODULE_SIGNAL signal, t_ModuleErrorSignalHandlerType notifier );
329 
330  /**
331  * Gets the modules base progress. This is actually a progress combiner, which bundles all progresses.
332  *
333  * \return the progress combiner for this module.
334  */
335  virtual boost::shared_ptr< WProgressCombiner > getRootProgressCombiner();
336 
337  /**
338  * Get the icon for this module in XPM format.
339  * \return The icon.
340  */
341  virtual const char** getXPMIcon() const;
342 
343  /**
344  * Gets the type of the module. This is useful for FAST differentiation between several modules like standard modules and data
345  * modules which play a special role in OpenWalnut/Kernel.
346  *
347  * \return the Type. If you do not overwrite this method, it will return MODULE_ARBITRARY.
348  */
349  virtual MODULE_TYPE getType() const;
350 
351  /**
352  * Completely disconnects all connected connectors of this module. This is useful to isolate a module (for deletion, removal from a container
353  * and so on.)
354  */
355  void disconnect();
356 
357  /**
358  * Gives a list of all WDisconnectCombiners possible. Please note that while the list exists, connections might change.
359  *
360  * \return the list of possible disconnect operations
361  */
362  WCombinerTypes::WDisconnectList getPossibleDisconnections();
363 
364  /**
365  * Returns the local path of the module. Whenever you try to load local resources, use this path. It is especially useful for shader loading.
366  *
367  * \return the local module path.
368  */
369  boost::filesystem::path getLocalPath() const;
370 
371  /**
372  * Returns the absolute path to the library containing this module.
373  *
374  * \return the path.
375  */
376  boost::filesystem::path getLibPath() const;
377 
378  /**
379  * Returns the name of the package the module belongs to, The package name basically is the name of the
380  * library containing this and maybe other modules. Your build system manages this. The package name is used to identify the resources for
381  * the modules in the library (a.k.a package).
382  *
383  * \return the name
384  */
385  std::string getPackageName() const;
386 
387  /**
388  * Checks whether the module was marked as deprecated.
389  *
390  * \return true if deprecated
391  */
392  bool isDeprecated() const;
393 
394  /**
395  * Queries the deprecation message of a module if specified. If not specified, an empty string is returned. Check \ref isDeprecated first.
396  *
397  * \return deprecation message
398  */
399  std::string getDeprecationMessage() const;
400 
401  /**
402  * The meta information of this module. This contains several information like name, description, icons, help links and so on. It, at least,
403  * contains the name.
404  *
405  * \return the meta info object for this module.
406  */
408 
409  /**
410  * Get the UUID of the module instance. Use this when you need to guarantee a unique instance name, even across multiple OW sessions. The
411  * UUID gets set by the initialize method once and can never be changed.
412  *
413  * \return the UUID as string.
414  */
415  const std::string& getUUID() const;
416 
417  /**
418  * Find a module instance by UUID.
419  *
420  * \param uuid the uuid to search for.
421  *
422  * \return the module, or NULL if not found
423  */
424  static SPtr findByUUID( std::string uuid );
425 
426 protected:
427  /**
428  * Entry point after loading the module. Runs in separate thread.
429  */
430  virtual void moduleMain() = 0;
431 
432  /**
433  * Thread entry point. Calls moduleMain and sends error notification if needed.
434  */
435  void threadMain();
436 
437  /**
438  * This method is called if an exception was caught, which came from the custom thread code. This method is virtual and allows you to
439  * overwrite the default behaviour. If you overwrite this method, you should call \ref WThreadedRunner::handleDeadlyException or
440  * WThreadedRunner::onThreadException if you are finished with your customized code.
441  *
442  * \param e the exception that was caught.
443  */
444  virtual void onThreadException( const WException& e );
445 
446  /**
447  * Sets the container this module is associated with.
448  *
449  * \param container the container to associate with.
450  */
451  void setAssociatedContainer( boost::shared_ptr< WModuleContainer > container );
452 
453  // **************************************************************************************************************************
454  //
455  // Connector Management
456  //
457  // **************************************************************************************************************************
458 
459  /**
460  * Initialize connectors in this function. This function must not be called multiple times for one module instance.
461  * The module container manages calling those functions -> so just implement it.
462  */
463  virtual void connectors();
464 
465  /**
466  * Initialize properties in this function. This function must not be called multiple times for one module instance.
467  * The module container manages calling those functions -> so just implement it. Once initialized the number and type
468  * of all properties should be set.
469  */
470  virtual void properties();
471 
472  /**
473  * Initialize requirements in this function. This function must not be called multiple times for one module instance.
474  * The module should always implement this. Using this method, a module can tell the kernel what it needs to run properly. For example, it
475  * can require a running graphics engine or, in the case of module containers, other modules.
476  */
477  virtual void requirements();
478 
479  /**
480  * This function allows module programmers to mark their modules deprecated in a user-friendly way. If you implement this function, you need
481  * to specify an text which should mention an alternative module.
482  *
483  * \note do not add sentences like "this module is deprecated" or similar, since the GUI the user is using already shows this message. The
484  * message should say WHY it is deprecated and what alternative module is available.
485  * \return deprecation message
486  */
487  virtual std::string deprecated() const;
488 
489  /**
490  * Manages initialization. Gets called by module container and ensures all properties, requirements, and connectors are properly set up.
491  *
492  * \throw WModuleConnectorInitFailed if called multiple times.
493  */
494  void initialize();
495 
496  /**
497  * Called whenever the module should shutdown.
498  */
499  virtual void cleanup();
500 
501  /**
502  * Adds the specified connector to the list of inputs.
503  *
504  * \param con the connector.
505  */
506  void addConnector( boost::shared_ptr<WModuleInputConnector> con );
507 
508  /**
509  * Adds the specified connector to the list of outputs.
510  *
511  * \param con the connector.
512  */
513  void addConnector( boost::shared_ptr<WModuleOutputConnector> con );
514 
515  /**
516  * Removes all connectors properly. It disconnects the connectors and cleans the connectors list.
517  */
518  void removeConnectors();
519 
520  /**
521  * Callback for m_active. Overwrite this in your modules to handle m_active changes separately.
522  */
523  virtual void activate();
524 
525  // **************************************************************************************************************************
526  //
527  // Signal handlers that HAVE to be in every module. By default they do nothing. You should overwrite them to get notified
528  // with the corresponding signal
529  //
530  // **************************************************************************************************************************
531 
532  /**
533  * Gives the signal handler function responsible for a given signal. Modules defining own signal handlers should overwrite
534  * this function. This function is protected since boost::functions are callable, which is what is not wanted here. Just
535  * signals should call them.
536  *
537  * \param signal the signal to get the handler for.
538  *
539  * \return the signal handler for "signal".
540  */
541  virtual const t_GenericSignalHandlerType getSignalHandler( MODULE_CONNECTOR_SIGNAL signal );
542 
543  /**
544  * Gets called whenever a connector gets connected to the specified input.
545  *
546  * \param here the connector of THIS module that got connected to "there"
547  * \param there the connector that has been connected with the connector "here" of this module.
548  */
549  virtual void notifyConnectionEstablished( boost::shared_ptr<WModuleConnector> here,
550  boost::shared_ptr<WModuleConnector> there );
551  /**
552  * Gets called whenever a connection between a remote and local connector gets closed.
553  *
554  * \param here the connector of THIS module getting disconnected.
555  * \param there the connector of the other module getting disconnected.
556  */
557  virtual void notifyConnectionClosed( boost::shared_ptr<WModuleConnector> here, boost::shared_ptr<WModuleConnector> there );
558 
559  /**
560  * Gets called when the data on one input connector changed.
561  *
562  * \param input the input connector receiving the change.
563  * \param output the output connector sending the change notification.
564  */
565  virtual void notifyDataChange( boost::shared_ptr<WModuleConnector> input,
566  boost::shared_ptr<WModuleConnector> output );
567 
568  /**
569  * Call this whenever your module is ready and can react on property changes.
570  */
571  void ready();
572 
573  /**
574  * Logger instance for comfortable info logging. Simply use logInfo() << "my info".
575  *
576  * \return the logger stream.
577  */
579 
580  /**
581  * Logger instance for comfortable debug logging. Simply use logDebug() << "my debug".
582  *
583  * \return the logger stream.
584  */
586 
587  /**
588  * Logger instance for comfortable warning- logs. Simply use logWarning() << "my warning".
589  *
590  * \return the logger stream.
591  */
593 
594  /**
595  * Logger instance for comfortable error logging. Simply use logError() << "my error".
596  *
597  * \return the logger stream.
598  */
600 
601  // **************************************************************************************************************************
602  //
603  // Loading Management
604  //
605  // **************************************************************************************************************************
606 
607  /**
608  * Sets the local module path. This gets called by the module loader.
609  *
610  * \param path the local path.
611  */
612  void setLocalPath( boost::filesystem::path path );
613 
614  /**
615  * Set the path to the library which contains this module. This is usually set by \ref WModuleLoader.
616  *
617  * \param path the path to the library. Needs to be absolute.
618  */
619  void setLibPath( boost::filesystem::path path );
620 
621  /**
622  * Set the package name. This basically is the library name of the lib containing this module. The package name is used to identify resources
623  * and other things which belong to a library (a.k.a. package).
624  *
625  * \param name the name to set
626  */
627  void setPackageName( std::string name );
628 
629  // **************************************************************************************************************************
630  //
631  // Members
632  //
633  // **************************************************************************************************************************
634 
635  /**
636  * The property object for the module.
637  */
638  boost::shared_ptr< WProperties > m_properties;
639 
640  /**
641  * The property object for the module containing only module whose purpose is "PV_PURPOSE_INFORMNATION". It is useful to define some property
642  * 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
643  * m_properties.
644  */
645  boost::shared_ptr< WProperties > m_infoProperties;
646 
647  /**
648  * Progress indicator used as parent for all progress' of this module.
649  */
650  boost::shared_ptr< WProgressCombiner > m_progress;
651 
652  /**
653  * True if everything is initialized and ready to be used.
654  */
656 
657  /**
658  * True if container got associated with this flag.
659  */
661 
662  /**
663  * True if associated && initialized.
664  */
666 
667  /**
668  * True if ready() was called.
669  */
671 
672  /**
673  * It is true whenever m_isReady or WThreadedRunner::m_isCrashed is true. This is mostly useful for functions
674  * which need to wait for a module to get ready.
675  */
677 
678  /**
679  * True if the module currently is running.
680  */
682 
683  /**
684  * Flag to denote whether the module container and the project loader have finished their work. \see isLoadFinished.
685  */
687 
688  /**
689  * Flag denoting the current restore mode. \see setRestoreNeeded
690  */
692 
693  /**
694  * Progress indicator for the "ready" state.
695  */
696  boost::shared_ptr< WProgress > m_readyProgress;
697 
698  /**
699  * The internal state of the module. This is, by default, simply the exit flag from WThreadedRunner.
700  */
702 
703  /**
704  * The container this module belongs to.
705  */
706  boost::shared_ptr< WModuleContainer > m_container;
707 
708  /**
709  * Set of input connectors associated with this module.
710  */
711  InputConnectorList m_inputConnectors;
712 
713  /**
714  * Set of output connectors associated with this module.
715  */
716  OutputConnectorList m_outputConnectors;
717 
718  /**
719  * True whenever the module should be active
720  */
721  WPropBool m_active;
722 
723  /**
724  * This property holds a user specified name for the current module instance.
725  */
726  WPropString m_runtimeName;
727 
728  /**
729  * 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
730  * module loader. Use this to load shaders and so on.
731  */
732  boost::filesystem::path m_localPath;
733 
734  /**
735  * The absolute path to the library containing this module.
736  */
737  boost::filesystem::path m_libPath;
738 
739  /**
740  * The name of the lib/the package containing this module.
741  */
742  std::string m_packageName;
743 
744  /**
745  * The type of the requirement list.
746  */
747  typedef std::vector< WRequirement* > Requirements;
748 
749  /**
750  * The list of requirements.
751  */
752  Requirements m_requirements;
753 
754 private:
755  /**
756  * Lock for m_inputConnectors.
757  */
758  // boost::shared_mutex m_inputConnectorsLock;
759 
760  /**
761  * Lock for m_outputConnectors.
762  */
763  // boost::shared_mutex m_outputConnectorsLock;
764 
765  /**
766  * Module meta information. Set by the factory creating the module instance.
767  */
769 
770  /**
771  * Signal fired whenever a module main thread is ready.
772  */
773  t_ModuleGenericSignalType signal_ready;
774 
775  /**
776  * Signal fired whenever a module main thread throws an exception/error.
777  */
778  t_ModuleErrorSignalType signal_error;
779 
780  /**
781  * This method checks whether all the requirements of the module are complied.
782  *
783  * \return the requirement that has failed.
784  */
785  const WRequirement* checkRequirements() const;
786 
787  /**
788  * The unique ID of the module instance.
789  */
790  std::string m_uuid;
791 
792  /**
793  * Set a uuid. If the specified string is empty, a new one gets created.
794  *
795  * \param uuid the uuid to set.
796  */
797  void setUUID( std::string uuid );
798 };
799 
800 /**
801  * Simply a list of modules. The type is used by the following macros and typedefs
802  */
803 typedef std::vector< boost::shared_ptr< WModule > > WModuleList;
804 
805 /**
806  * The signature used for the module loading entry point
807  */
808 typedef void ( *W_LOADABLE_MODULE_SIGNATURE )( WModuleList& );
809 
810 /**
811  * The signature used for the loaded toolbox as arbitrary registration function.
812  */
813 typedef void ( *W_LOADABLE_REGISTERARBITRARY_SIGNATURE )( const boost::filesystem::path& );
814 
815 /**
816  * The following macro is used by modules so the factory can acquire a prototype instance from a shared library using the symbol.
817  * You can write this symbol for your own if you need to add multiple modules to the list. This one is for convenience.
818  *
819  * \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
820  * pointer causes segmentation faults during load.
821  */
822 #define W_LOADABLE_MODULE( MODULECLASS ) \
823 extern "C" void WLoadModule( WModuleList& m ) { m.push_back( boost::shared_ptr< WModule >( new MODULECLASS ) ); } // NOLINT
824 
825 /**
826  * The corresponding symbol name.
827  */
828 #define W_LOADABLE_MODULE_SYMBOL "WLoadModule"
829 
830 /**
831  * THe register function's symbol name.
832  */
833 #define W_LOADABLE_REGISTERARBITRARY_SYMBOL "WRegisterArbitrary"
834 
835 /**
836  * \defgroup modules Modules
837  *
838  * \brief
839  * This group contains modules of OpenWalnut.
840  * The term modules can be understood as "plugin" or "algorithm" in this context.
841  */
842 #endif // WMODULE_H
843 
t_ModuleErrorSignalType signal_error
Signal fired whenever a module main thread throws an exception/error.
Definition: WModule.h:778
virtual boost::signals2::connection subscribeSignal(MODULE_SIGNAL signal, t_ModuleGenericSignalHandlerType notifier)
Connects a specified notify function with a signal this module instance is offering.
Definition: WModule.cpp:384
boost::shared_ptr< WModuleContainer > m_container
The container this module belongs to.
Definition: WModule.h:706
void reportRestoreComplete()
Called by loaders to tell the module that loading has been completed.
Definition: WModule.cpp:647
wlog::WStreamedLogger errorLog() const
Logger instance for comfortable error logging.
Definition: WModule.cpp:571
virtual void connectors()
Initialize connectors in this function.
Definition: WModule.cpp:209
virtual WModuleMetaInformation::ConstSPtr getMetaInformation() const
The meta information of this module.
Definition: WModule.cpp:230
Class able to create a new copy of an arbitrary module.
void setUUID(std::string uuid)
Set a uuid.
Definition: WModule.cpp:657
boost::shared_ptr< const WModule > ConstSPtr
Shared pointer to a const WModule.
Definition: WModule.h:126
WBoolFlag m_isReadyOrCrashed
It is true whenever m_isReady or WThreadedRunner::m_isCrashed is true.
Definition: WModule.h:676
void ready()
Call this whenever your module is ready and can react on property changes.
Definition: WModule.cpp:506
virtual const char ** getXPMIcon() const
Get the icon for this module in XPM format.
Definition: WModule.cpp:494
boost::shared_ptr< const WModuleMetaInformation > ConstSPtr
Convenience typedef for a boost::shared_ptr< const WModuleMetaInformation >.
std::vector< WRequirement * > Requirements
The type of the requirement list.
Definition: WModule.h:747
This is a simple class which forwards output data to output data connectors.
virtual void moduleMain()=0
Entry point after loading the module.
virtual void onThreadException(const WException &e)
This method is called if an exception was caught, which came from the custom thread code...
Definition: WModule.cpp:551
Loads module prototypes from shared objects in a given directory and injects it into the module facto...
Definition: WModuleLoader.h:47
boost::shared_ptr< WProperties > getProperties() const
Return a pointer to the properties object of the module.
Definition: WModule.cpp:479
void removeConnectors()
Removes all connectors properly.
Definition: WModule.cpp:195
Class representing a single module of OpenWalnut.
Definition: WModule.h:83
WBoolFlag m_isUsable
True if associated && initialized.
Definition: WModule.h:665
void setAssociatedContainer(boost::shared_ptr< WModuleContainer > container)
Sets the container this module is associated with.
Definition: WModule.cpp:274
std::vector< boost::shared_ptr< WModuleOutputConnector > > OutputConnectorList
The type for the list of output connectors.
Definition: WModule.h:116
This is a simple class which forwards input data to input data connectors.
Definition: WModule.h:76
void setLibPath(boost::filesystem::path path)
Set the path to the library which contains this module.
Definition: WModule.cpp:596
boost::shared_ptr< WModuleMetaInformation > SPtr
Convenience typedef for a boost::shared_ptr< WModuleMetaInformation >.
WModuleMetaInformation::SPtr m_meta
Lock for m_inputConnectors.
Definition: WModule.h:768
boost::shared_ptr< WModuleOutputConnector > getOutputConnector(std::string name)
Finds the named connector for the module.
Definition: WModule.cpp:343
WBoolFlag m_isRunning
True if the module currently is running.
Definition: WModule.h:681
std::string getPackageName() const
Returns the name of the package the module belongs to, The package name basically is the name of the ...
Definition: WModule.cpp:611
boost::shared_ptr< WModuleConnector > findConnector(std::string name)
Finds the named connector for the module.
Definition: WModule.cpp:357
bool isRestoreNeeded() const
Check whether this module is in restore mode.
Definition: WModule.cpp:637
boost::shared_ptr< WProperties > getInformationProperties() const
Return a pointer to the information properties object of the module.
Definition: WModule.cpp:484
boost::shared_ptr< WProgressCombiner > m_progress
Progress indicator used as parent for all progress' of this module.
Definition: WModule.h:650
void waitRestored()
This method waits for the module to be restored completely.
Definition: WModule.cpp:626
boost::filesystem::path getLocalPath() const
Returns the local path of the module.
Definition: WModule.cpp:591
const WBoolFlag & isReadyOrCrashed() const
This is the logical or of isReady and isCrashed.
Definition: WModule.cpp:451
WCombinerTypes::WDisconnectList getPossibleDisconnections()
Gives a list of all WDisconnectCombiners possible.
Definition: WModule.cpp:162
virtual void notifyConnectionClosed(boost::shared_ptr< WModuleConnector > here, boost::shared_ptr< WModuleConnector > there)
Gets called whenever a connection between a remote and local connector gets closed.
Definition: WModule.cpp:467
Class offering an instantiate-able data connection between modules.
Definition: WModule.h:75
static SPtr findByUUID(std::string uuid)
Find a module instance by UUID.
Definition: WModule.cpp:670
WPropBool m_active
True whenever the module should be active.
Definition: WModule.h:721
Class offering an instantiate-able data connection between modules.
Definition: WModule.h:77
virtual void activate()
Callback for m_active.
Definition: WModule.cpp:221
virtual void requirements()
Initialize requirements in this function.
Definition: WModule.cpp:217
Interface class for the concept "Prototype".
Definition: WPrototyped.h:39
Base class for all classes needing to be executed in a separate thread.
const WBoolFlag & isReady() const
Checks whether this module is ready.
Definition: WModule.cpp:446
virtual void properties()
Initialize properties in this function.
Definition: WModule.cpp:213
void setRestoreNeeded(bool restore=true)
Change the restore mode.
Definition: WModule.cpp:642
WBoolFlag m_isReady
True if ready() was called.
Definition: WModule.h:670
virtual ~WModule()
Destructor.
Definition: WModule.cpp:104
boost::shared_ptr< WModuleContainer > getAssociatedContainer() const
The container this module is associated with.
Definition: WModule.cpp:269
Resource class for streamed logging.
Definition: WLogger.h:183
Class allowing multiple conditions to be used for one waiting cycle.
Definition: WConditionSet.h:46
const InputConnectorList & getInputConnectors() const
Gives back input connectors.
Definition: WModule.cpp:288
WBoolFlag m_isAssociated
True if container got associated with this flag.
Definition: WModule.h:660
boost::filesystem::path m_localPath
The path where the module binary resides in.
Definition: WModule.h:732
const OutputConnectorList & getOutputConnectors() const
Gives back output connectors.
Definition: WModule.cpp:293
Base class for all possible kinds of requirements.
Definition: WRequirement.h:37
boost::shared_ptr< WProperties > m_properties
The property object for the module.
Definition: WModule.h:638
void disconnect()
Completely disconnects all connected connectors of this module.
Definition: WModule.cpp:147
virtual MODULE_TYPE getType() const
Gets the type of the module.
Definition: WModule.cpp:283
boost::shared_ptr< WModuleOutputConnector > findOutputConnector(std::string name)
Finds the named connector for the module.
Definition: WModule.cpp:327
WModule()
Constructs a new WModule instance.
Definition: WModule.cpp:61
std::string m_packageName
The name of the lib/the package containing this module.
Definition: WModule.h:742
const WRequirement * checkRequirements() const
This method checks whether all the requirements of the module are complied.
Definition: WModule.cpp:513
boost::filesystem::path m_libPath
The absolute path to the library containing this module.
Definition: WModule.h:737
const WBoolFlag & isRunning() const
Returns a flag denoting whether the thread currently is running or nor.
Definition: WModule.cpp:456
virtual std::string deprecated() const
This function allows module programmers to mark their modules deprecated in a user-friendly way...
Definition: WModule.cpp:225
Class implementing output connection functionality between modules.
boost::filesystem::path getLibPath() const
Returns the absolute path to the library containing this module.
Definition: WModule.cpp:601
boost::shared_ptr< WModule > SPtr
Shared pointer to a WModule.
Definition: WModule.h:121
void initialize()
Manages initialization.
Definition: WModule.cpp:235
boost::shared_ptr< WProperties > m_infoProperties
The property object for the module containing only module whose purpose is "PV_PURPOSE_INFORMNATION"...
Definition: WModule.h:645
WBoolFlag m_initialized
True if everything is initialized and ready to be used.
Definition: WModule.h:655
boost::shared_ptr< WModuleInputConnector > getInputConnector(std::string name)
Finds the named connector for the module.
Definition: WModule.cpp:314
std::vector< boost::shared_ptr< WModuleInputConnector > > InputConnectorList
The type for the list of input connectors.
Definition: WModule.h:111
const WBoolFlag & isUseable() const
Checks whether the module instance is ready to be used.
Definition: WModule.cpp:440
virtual boost::shared_ptr< WProgressCombiner > getRootProgressCombiner()
Gets the modules base progress.
Definition: WModule.cpp:489
virtual void cleanup()
Called whenever the module should shutdown.
Definition: WModule.cpp:263
WPropString m_runtimeName
This property holds a user specified name for the current module instance.
Definition: WModule.h:726
wlog::WStreamedLogger warnLog() const
Logger instance for comfortable warning- logs.
Definition: WModule.cpp:581
boost::shared_ptr< WModuleConnector > getConnector(std::string name)
Finds the named connector for the module.
Definition: WModule.cpp:370
std::string getDeprecationMessage() const
Queries the deprecation message of a module if specified.
Definition: WModule.cpp:621
void setPackageName(std::string name)
Set the package name.
Definition: WModule.cpp:606
Class implementing input connection functionality between modules.
const std::string & getUUID() const
Get the UUID of the module instance.
Definition: WModule.cpp:652
virtual boost::shared_ptr< WModule > factory() const =0
Due to the prototype design pattern used to build modules, this method returns a new instance of this...
wlog::WStreamedLogger infoLog() const
Logger instance for comfortable info logging.
Definition: WModule.cpp:566
InputConnectorList m_inputConnectors
Set of input connectors associated with this module.
Definition: WModule.h:711
const WBoolFlag & isAssociated() const
Checks whether this module is associated with an container.
Definition: WModule.cpp:435
virtual void notifyConnectionEstablished(boost::shared_ptr< WModuleConnector > here, boost::shared_ptr< WModuleConnector > there)
Gets called whenever a connector gets connected to the specified input.
Definition: WModule.cpp:461
void setLocalPath(boost::filesystem::path path)
Sets the local module path.
Definition: WModule.cpp:586
t_ModuleGenericSignalType signal_ready
Signal fired whenever a module main thread is ready.
Definition: WModule.h:773
Class able to contain other modules.
Basic exception handler.
Definition: WException.h:38
Requirements m_requirements
The list of requirements.
Definition: WModule.h:752
WBoolFlag m_isLoadFinished
Flag to denote whether the module container and the project loader have finished their work...
Definition: WModule.h:686
const WBoolFlag & isInitialized() const
Determines whether the module instance is properly initialized.
Definition: WModule.cpp:430
bool m_restoreMode
Flag denoting the current restore mode.
Definition: WModule.h:691
Base class for modelling connections between kernel modules.
WConditionSet m_moduleState
The internal state of the module.
Definition: WModule.h:701
virtual void notifyDataChange(boost::shared_ptr< WModuleConnector > input, boost::shared_ptr< WModuleConnector > output)
Gets called when the data on one input connector changed.
Definition: WModule.cpp:473
void addConnector(boost::shared_ptr< WModuleInputConnector > con)
Adds the specified connector to the list of inputs.
Definition: WModule.cpp:109
boost::shared_ptr< WModuleInputConnector > findInputConnector(std::string name)
Finds the named connector for the module.
Definition: WModule.cpp:298
void threadMain()
Thread entry point.
Definition: WModule.cpp:527
boost::shared_ptr< WProgress > m_readyProgress
Progress indicator for the "ready" state.
Definition: WModule.h:696
bool isDeprecated() const
Checks whether the module was marked as deprecated.
Definition: WModule.cpp:616
std::string m_uuid
The unique ID of the module instance.
Definition: WModule.h:790
wlog::WStreamedLogger debugLog() const
Logger instance for comfortable debug logging.
Definition: WModule.cpp:576
OutputConnectorList m_outputConnectors
Set of output connectors associated with this module.
Definition: WModule.h:716
virtual const t_GenericSignalHandlerType getSignalHandler(MODULE_CONNECTOR_SIGNAL signal)
Gives the signal handler function responsible for a given signal.
Definition: WModule.cpp:412