Belle II Software  release-08-01-10
Module.h
1 /**************************************************************************
2  * basf2 (Belle II Analysis Software Framework) *
3  * Author: The Belle II Collaboration *
4  * *
5  * See git log for contributors and copyright holders. *
6  * This file is licensed under LGPL-3.0, see LICENSE.md. *
7  **************************************************************************/
8 
9 #pragma once
10 
11 #include <framework/core/ModuleParamList.h>
12 #include <framework/core/ModuleParamList.templateDetails.h>
13 #include <framework/core/ModuleCondition.h>
14 #include <framework/core/PathElement.h>
15 
16 #include <framework/logging/LogConfig.h>
17 
18 #include <list>
19 #include <string>
20 #include <memory>
21 
22 namespace boost {
23  namespace python {
24  class list;
25  class dict;
26  namespace api {
27  class object;
28  }
29  using api::object;
30  }
31 }
32 
33 namespace Belle2 {
39  class Module;
40  class Path;
41 
43  typedef std::shared_ptr<Module> ModulePtr;
44 
72  class Module : public PathElement {
73 
74  public:
75 
78  c_Input = 1,
79  c_Output = 2,
85  };
86 
89 
99  Module();
100 
109  virtual void initialize() {};
110 
133  [[deprecated("will be removed in release-05.")]]
134  virtual std::vector<std::string> getFileNames(__attribute__((unused)) bool outputFiles)
135  {
136  return std::vector<std::string>();
137  }
138 
147  virtual void beginRun() {};
148 
157  virtual void event() {};
158 
166  virtual void endRun() {};
167 
176  virtual void terminate() {};
177 
187  const std::string& getName() const {return m_name;}
188 
192  const std::string& getType() const;
193 
197  const std::string& getPackage() const {return m_package;}
198 
202  const std::string& getDescription() const {return m_description;}
203 
214  void setName(const std::string& name) { m_name = name; };
220  void setPropertyFlags(unsigned int propertyFlags);
221 
226 
230  void setLogConfig(const LogConfig& logConfig) {m_logConfig = logConfig;}
231 
235  void setLogLevel(int logLevel);
236 
240  void setDebugLevel(int debugLevel);
241 
245  void setAbortLevel(int abortLevel);
246 
253  void setLogInfo(int logLevel, unsigned int logInfo);
254 
255 
271  void if_value(const std::string& expression, const std::shared_ptr<Path>& path,
272  EAfterConditionPath afterConditionPath = EAfterConditionPath::c_End);
273 
289  void if_false(const std::shared_ptr<Path>& path, EAfterConditionPath afterConditionPath = EAfterConditionPath::c_End);
290 
306  void if_true(const std::shared_ptr<Path>& path, EAfterConditionPath afterConditionPath = EAfterConditionPath::c_End);
307 
311  bool hasCondition() const { return not m_conditions.empty(); };
312 
315  {
316  if (m_conditions.empty()) {
317  return nullptr;
318  } else {
319  return &m_conditions.front();
320  }
321  }
322 
324  const std::vector<ModuleCondition>& getAllConditions() const
325  {
326  return m_conditions;
327  }
328 
339  bool evalCondition() const;
340 
342  std::shared_ptr<Path> getConditionPath() const;
343 
346 
348  std::vector<std::shared_ptr<Path>> getAllConditionPaths() const;
349 
355  bool hasProperties(unsigned int propertyFlags) const;
356 
360  bool hasUnsetForcedParams() const;
361 
363  const ModuleParamList& getParamList() const { return m_moduleParamList; }
364 
374  template<typename T>
375  ModuleParam<T>& getParam(const std::string& name) const;
376 
378  bool hasReturnValue() const { return m_hasReturnValue; }
381  int getReturnValue() const { return m_returnValue; }
382 
388  std::shared_ptr<PathElement> clone() const override;
389 
390 
391  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
392  // Python API
393  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
394 
402  std::shared_ptr<boost::python::list> getParamInfoListPython() const;
403 
407  static void exposePythonAPI();
408 
409  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
410 
411 
412  protected:
414 
420  virtual void def_initialize() { initialize(); }
421 
426  virtual void def_beginRun() { beginRun(); }
427 
432  virtual void def_event() { event(); }
433 
439  virtual void def_endRun() { endRun(); }
440 
445  virtual void def_terminate() { terminate(); }
447 
448 
454  void setDescription(const std::string& description);
455 
457  void setType(const std::string& type);
458 
467  template<typename T>
468  void addParam(const std::string& name, T& paramVariable, const std::string& description, const T& defaultValue);
469 
478  template<typename T>
479  void addParam(const std::string& name, T& paramVariable, const std::string& description);
480 
488  void setReturnValue(int value);
489 
498  void setReturnValue(bool value);
499 
501  void setParamList(const ModuleParamList& params) { m_moduleParamList = params; }
502 
503 
504  private:
506  std::list<ModulePtr> getModules() const override { return std::list<ModulePtr>(); }
507 
508  std::string m_name;
509  std::string m_type;
510  std::string m_package;
511  std::string m_description;
512  unsigned int m_propertyFlags;
521  std::vector<ModuleCondition> m_conditions;
523  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
524  // Python API
525  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
526 
528  std::string getPathString() const override;
529 
539  void setParamPython(const std::string& name, const boost::python::object& pyObj);
540 
548  void setParamPythonDict(const boost::python::dict& dictionary);
549 
550  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
551 
552  friend class ModuleProxyBase;
553  };
554 
555 
556  //------------------------------------------------------
557  // Implementation of template based methods
558  //------------------------------------------------------
559  template<typename T>
560  void Module::addParam(const std::string& name, T& paramVariable, const std::string& description, const T& defaultValue)
561  {
562  m_moduleParamList.addParameter(name, paramVariable, description, defaultValue);
563  }
564 
565 
566  template<typename T>
567  void Module::addParam(const std::string& name, T& paramVariable, const std::string& description)
568  {
569  m_moduleParamList.addParameter(name, paramVariable, description);
570  }
571 
572  template<typename T>
573  ModuleParam<T>& Module::getParam(const std::string& name) const
574  {
575  return m_moduleParamList.getParameter<T>(name);
576  }
577 
578 
579  //------------------------------------------------------
580  // Define convenient typdefs
581  //------------------------------------------------------
582 
584  typedef std::list<ModulePtr> ModulePtrList;
585 
586 
587  //------------------------------------------------------
588  // Proxy class for creating an instance of the module
589  //------------------------------------------------------
598 
599  public:
606  ModuleProxyBase(std::string moduleType, std::string package);
607 
611  virtual ~ModuleProxyBase() {};
612 
619  {
621  nm->setType(m_moduleType);
622  nm->setName(m_moduleType);
623  nm->m_package = m_package;
624  return nm;
625  }
626 
630  const std::string& getModuleName() const {return m_moduleType; }
631 
632 
633  protected:
635  virtual Module* createInstance() const = 0;
636 
637  std::string m_moduleType;
638  std::string m_package;
639  };
640 
641 
642 #ifndef _PACKAGE_
643 #define _PACKAGE_ ""
644 #endif
645 
646  //------------------------------------------------------
647  // Define convenient macro
648  //------------------------------------------------------
650 #define REG_MODULE(moduleName) namespace { struct ModuleProxy##moduleName: public ModuleProxyBase { \
651  ModuleProxy##moduleName(): ModuleProxyBase(#moduleName, "" _PACKAGE_) {} \
652  virtual ::Belle2::Module* createInstance() const override final { return new moduleName##Module(); } \
653  } proxy##moduleName##Module; }
654 
656 } // end namespace Belle2
The LogConfig class.
Definition: LogConfig.h:22
Wraps a condition set on a Module instance.
EAfterConditionPath
Different options for behaviour after a conditional path was executed.
@ c_End
End current event after the conditional path.
The Module parameter list class.
A single parameter of the module.
Definition: ModuleParam.h:34
The base module proxy class is used to create new instances of a module.
Definition: Module.h:597
virtual ~ModuleProxyBase()
The destructor of the ModuleProxyBase class.
Definition: Module.h:611
ModulePtr createModule() const
Abstract method which creates a new module and returns a shared pointer to it.
Definition: Module.h:618
ModuleProxyBase(std::string moduleType, std::string package)
The constructor of the ModuleProxyBase class.
Definition: Module.cc:497
std::string m_moduleType
The type name of the module.
Definition: Module.h:637
const std::string & getModuleName() const
Returns the module name of the module associated to this proxy.
Definition: Module.h:630
virtual Module * createInstance() const =0
create a new instance of the module in question
std::string m_package
Package this module is found in (may be empty).
Definition: Module.h:638
Base class for Modules.
Definition: Module.h:72
void setLogLevel(int logLevel)
Configure the log level.
Definition: Module.cc:55
std::shared_ptr< boost::python::list > getParamInfoListPython() const
Returns a python list of all parameters.
Definition: Module.cc:279
const std::string & getDescription() const
Returns the description of the module.
Definition: Module.h:202
void if_value(const std::string &expression, const std::shared_ptr< Path > &path, EAfterConditionPath afterConditionPath=EAfterConditionPath::c_End)
Add a condition to the module.
Definition: Module.cc:79
std::list< ModulePtr > getModules() const override
no submodules, return empty list
Definition: Module.h:506
const ModuleParamList & getParamList() const
Return module param list.
Definition: Module.h:363
void setDescription(const std::string &description)
Sets the description of the module.
Definition: Module.cc:214
void setPropertyFlags(unsigned int propertyFlags)
Sets the flags for the module properties.
Definition: Module.cc:208
void if_true(const std::shared_ptr< Path > &path, EAfterConditionPath afterConditionPath=EAfterConditionPath::c_End)
A simplified version to set the condition of the module.
Definition: Module.cc:90
virtual void def_endRun()
This method can receive that the current run ends as a call from the Python side.
Definition: Module.h:439
std::vector< std::shared_ptr< Path > > getAllConditionPaths() const
Return all condition paths currently set (no matter if the condition is true or not).
Definition: Module.cc:150
int m_returnValue
The return value.
Definition: Module.h:519
Module()
Constructor.
Definition: Module.cc:30
const std::string & getType() const
Returns the type of the module (i.e.
Definition: Module.cc:41
void setReturnValue(int value)
Sets the return value for this module as integer.
Definition: Module.cc:220
EModulePropFlags
Each module can be tagged with property flags, which indicate certain features of the module.
Definition: Module.h:77
@ c_HistogramManager
This module is used to manage histograms accumulated by other modules.
Definition: Module.h:81
@ c_Input
This module is an input module (reads data).
Definition: Module.h:78
@ c_DontCollectStatistics
No statistics is collected for this module.
Definition: Module.h:84
@ c_ParallelProcessingCertified
This module can be run in parallel processing mode safely (All I/O must be done through the data stor...
Definition: Module.h:80
@ c_InternalSerializer
This module is an internal serializer/deserializer for parallel processing.
Definition: Module.h:82
@ c_Output
This module is an output module (writes data).
Definition: Module.h:79
@ c_TerminateInAllProcesses
When using parallel processing, call this module's terminate() function in all processes().
Definition: Module.h:83
const std::vector< ModuleCondition > & getAllConditions() const
Return all set conditions for this module.
Definition: Module.h:324
void setLogConfig(const LogConfig &logConfig)
Set the log system configuration.
Definition: Module.h:230
virtual void event()
This method is the core of the module.
Definition: Module.h:157
virtual std::vector< std::string > getFileNames(bool outputFiles)
Return a list of output filenames for this modules.
Definition: Module.h:134
virtual void initialize()
Initialize the Module.
Definition: Module.h:109
void setAbortLevel(int abortLevel)
Configure the abort log level.
Definition: Module.cc:67
virtual void def_terminate()
Wrapper method for the virtual function terminate() that has the implementation to be used in a call ...
Definition: Module.h:445
virtual void beginRun()
Called when entering a new run.
Definition: Module.h:147
void setDebugLevel(int debugLevel)
Configure the debug messaging level.
Definition: Module.cc:61
void setParamPython(const std::string &name, const boost::python::object &pyObj)
Implements a method for setting boost::python objects.
Definition: Module.cc:234
virtual void def_initialize()
Wrappers to make the methods without "def_" prefix callable from Python.
Definition: Module.h:420
unsigned int m_propertyFlags
The properties of the module as bitwise or (with |) of EModulePropFlags.
Definition: Module.h:512
void if_false(const std::shared_ptr< Path > &path, EAfterConditionPath afterConditionPath=EAfterConditionPath::c_End)
A simplified version to add a condition to the module.
Definition: Module.cc:85
ModuleParamList m_moduleParamList
List storing and managing all parameter of the module.
Definition: Module.h:516
bool hasReturnValue() const
Return true if this module has a valid return value set.
Definition: Module.h:378
virtual void endRun()
This method is called if the current run ends.
Definition: Module.h:166
bool hasCondition() const
Returns true if at least one condition was set for the module.
Definition: Module.h:311
std::shared_ptr< Path > getConditionPath() const
Returns the path of the last true condition (if there is at least one, else reaturn a null pointer).
Definition: Module.cc:113
std::string m_type
The type of the module, saved as a string.
Definition: Module.h:509
const std::string & getName() const
Returns the name of the module.
Definition: Module.h:187
bool m_hasReturnValue
True, if the return value is set.
Definition: Module.h:518
virtual void def_beginRun()
Wrapper method for the virtual function beginRun() that has the implementation to be used in a call f...
Definition: Module.h:426
void setName(const std::string &name)
Set the name of the module.
Definition: Module.h:214
void setType(const std::string &type)
Set the module type.
Definition: Module.cc:48
static void exposePythonAPI()
Exposes methods of the Module class to Python.
Definition: Module.cc:325
LogConfig m_logConfig
The log system configuration of the module.
Definition: Module.h:514
Module::EAfterConditionPath getAfterConditionPath() const
What to do after the conditional path is finished.
Definition: Module.cc:133
std::vector< ModuleCondition > m_conditions
Module condition, only non-null if set.
Definition: Module.h:521
void setParamList(const ModuleParamList &params)
Replace existing parameter list.
Definition: Module.h:501
std::shared_ptr< PathElement > clone() const override
Create an independent copy of this module.
Definition: Module.cc:179
bool hasProperties(unsigned int propertyFlags) const
Returns true if all specified property flags are available in this module.
Definition: Module.cc:160
std::string m_description
The description of the module.
Definition: Module.h:511
virtual void def_event()
Wrapper method for the virtual function event() that has the implementation to be used in a call from...
Definition: Module.h:432
std::string m_name
The name of the module, saved as a string (user-modifiable)
Definition: Module.h:508
ModuleCondition::EAfterConditionPath EAfterConditionPath
Forward the EAfterConditionPath definition from the ModuleCondition.
Definition: Module.h:88
const std::string & getPackage() const
Returns the package this module is in.
Definition: Module.h:197
const ModuleCondition * getCondition() const
Return a pointer to the first condition (or nullptr, if none was set)
Definition: Module.h:314
bool evalCondition() const
If at least one condition was set, it is evaluated and true returned if at least one condition return...
Definition: Module.cc:96
virtual void terminate()
This method is called at the end of the event processing.
Definition: Module.h:176
int getReturnValue() const
Return the return value set by this module.
Definition: Module.h:381
void setParamPythonDict(const boost::python::dict &dictionary)
Implements a method for reading the parameter values from a boost::python dictionary.
Definition: Module.cc:249
LogConfig & getLogConfig()
Returns the log system configuration.
Definition: Module.h:225
std::string m_package
Package this module is found in (may be empty).
Definition: Module.h:510
void setLogInfo(int logLevel, unsigned int logInfo)
Configure the printed log information for the given level.
Definition: Module.cc:73
bool hasUnsetForcedParams() const
Returns true and prints error message if the module has unset parameters which the user has to set in...
Definition: Module.cc:166
std::string getPathString() const override
return the module name.
Definition: Module.cc:192
Base for classes that can be elements of a Path.
Definition: PathElement.h:27
void addParam(const std::string &name, T &paramVariable, const std::string &description, const T &defaultValue)
Adds a new parameter to the module.
Definition: Module.h:560
ModuleParam< T > & getParameter(const std::string &name) const
Returns a reference to a parameter.
ModuleParam< T > & getParam(const std::string &name) const
Returns a reference to a parameter.
Definition: Module.h:573
std::shared_ptr< Module > ModulePtr
Defines a pointer to a module object as a boost shared pointer.
Definition: Module.h:40
std::list< ModulePtr > ModulePtrList
Defines a std::list of shared module pointers.
Definition: Module.h:584
void addParameter(const std::string &name, T &paramVariable, const std::string &description, const T &defaultValue)
Adds a new parameter to the module list.
Abstract base class for different kinds of events.