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