JeVois  1.3
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
Manager.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4 // California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5 //
6 // This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7 // redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8 // Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10 // License for more details. You should have received a copy of the GNU General Public License along with this program;
11 // if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 //
13 // Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14 // Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16 /*! \file */
17 
18 // This code is inspired by the Neuromorphic Robotics Toolkit (http://nrtkit.org)
19 
20 #pragma once
21 
23 #include <jevois/Types/Enum.H>
24 
25 #include <vector>
26 
27 // BEGIN_JEVOIS_CODE_SNIPPET manager1.C
28 namespace jevois
29 {
30  namespace manager
31  {
32  //! Parameter category \relates jevois::Manager
33  static ParameterCategory const ParamCateg("General Options");
34 
35  //! Parameter \relates jevois::Manager
36  JEVOIS_DECLARE_PARAMETER(help, bool, "Print this help message", false, ParamCateg);
37 
38 #ifdef JEVOIS_LDEBUG_ENABLE
39  //! Enum for Parameter \relates jevois::Manager
40  JEVOIS_DEFINE_ENUM_CLASS(LogLevel, (fatal) (error) (info) (debug));
41 #else
42  //! Enum for Parameter \relates jevois::Manager
43  JEVOIS_DEFINE_ENUM_CLASS(LogLevel, (fatal) (error) (info));
44 #endif
45 
46  //! Parameter \relates jevois::Manager
47  JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(loglevel, LogLevel, "Set the minimum log level to display",
48  LogLevel::info, LogLevel_Values, ParamCateg);
49 
50  //! Parameter \relates jevois::Manager
51  JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(tracelevel, unsigned int, "Set the minimum trace level to display",
52  0, ParamCateg);
53  }
54 
55  // ######################################################################
56  //! Manager of a hierarchy of Component objects
57  /*! A Manager should be the top-level Component of any hierarchy of Components. It is primarily responsible for
58  handling the setting of Parameter values via the command-line or otherwise.
59 
60  Users should only need to construct a Manager (including Engine, which derives from Manager), add any Component to
61  it, and then call init() on the Manager, which will parse all command line options, bind them to the relevant
62  Parameters, and call init() on all subComponents (which in turn calls init() on all of their subComponents,
63  etc.). See the documentation of Component for more information about the init() flow.
64 
65  \ingroup component */
66  class Manager : public Component,
67  public Parameter<manager::help, manager::loglevel, manager::tracelevel>
68  {
69  public:
70  // END_JEVOIS_CODE_SNIPPET
71 
72  //! @name Manager construction, destruction, parsing command-line arguments
73  //! @{
74 
75  //! Constructor without command-line args
76  /*! The command-line args should be passed later using setArgs(), before you init(), otherwise the manager will
77  issue a non-fatal warning. */
78  Manager(std::string const & instance = "TheManager");
79 
80  //! Constructor
81  /*! Creates the Manager, and optionally takes in the command line arguments. */
82  Manager(int argc, char const* argv[], std::string const & instance = "TheManager");
83 
84  //! Set the command-line arguments, call this before start() if args were not passed at construction
85  void setCommandLineArgs(int argc, char const* argv[]);
86 
87  //! Destructor
88  virtual ~Manager();
89 
90  //! @}
91 
92  //! @name Component hierarchies unser the Manager
93  //! @{
94 
95  //! Pseudo-constructor: construct a top-level Component
96  /*! A component of type Comp (which must derive from jevois::Component) will be created and added as a
97  sub-component of the manager (making it a so-called top-level component). The child logically "belongs" to the
98  Manager, and will automatically be deleted when the Manager is deleted. In addition to construction, the
99  component will be brought to the same initialized state as the Manager. */
100  template <class Comp, typename... Args>
101  std::shared_ptr<Comp> addComponent(std::string const & instanceName, Args && ...args);
102 
103  //! Use addComponent() on the Manager as opposed to jevois::Component::addSubComponent()
104  template <class Comp, typename... Args>
105  std::shared_ptr<Comp> addSubComponent(std::string const & instanceName, Args && ...args) = delete;
106 
107  //! Remove a top-level Component from the Manager, by shared_ptr
108  /*! \note Beware that the passed shared_ptr is invalidated in the process. A warning is issued if the use_count is
109  not down to zero after that (i.e., there are additional shared_ptr pointers to this Component floating around,
110  which prevent it from actually being deleted. */
111  template <class Comp>
112  void removeComponent(std::shared_ptr<Comp> & component);
113 
114  //! Use removeComponent() on the Manager as opposed to jevois::Component::removeSubComponent()
115  template <class Comp>
116  void removeSubComponent(std::shared_ptr<Comp> & component) = delete;
117 
118  //! Remove a top-level Component from the Manager, by instance name
119  void removeComponent(std::string const & instanceName, bool warnIfNotFound = true);
120 
121  //! Use removeComponent() on the Manager as opposed to jevois::Component::removeSubComponent()
122  void removeSubComponent(std::string const & instanceName, bool warnIfNotFound) = delete;
123 
124  //! Get a top-level component by instance name
125  /*! This method does a dynamic_pointer_cast to Comp if it is not the default (jevois::Component). Throws if
126  component is not found by instance name, or it is found but not of type Comp (if Comp is specified). Note that
127  once you hold a shared_ptr to a Component, it is guaranteed that the component will not be destroyed until
128  that shared_ptr is released. If the JeVois system tries to destroy the component, e.g., someone calls
129  removeComponent(), the component will be un-initialized and its parent will be unset, so it will not be
130  fully operational, and will be actually deleted when the last shared_ptr to it runs out of scope. */
131  template <class Comp = jevois::Component>
132  std::shared_ptr<Comp> getComponent(std::string const & instanceName) const;
133 
134  //! Use getComponent() on the Manager as opposed to jevois::Component::getSubComponent()
135  template <class Comp>
136  std::shared_ptr<Comp> getSubComponent(std::string const & instanceName) const = delete;
137 
138  //! @}
139 
140  //! @name Manager runtime
141  //! @{
142 
143  //! Users can call init() on the Manager to initialize the whole Component tree
144  /*! This will, in particular, trigger parsing of command-line arguments. */
145  using Component::init;
146 
147  //! Users can call uninit() on the Manager to un-initialize the whole Component tree
148  /*! If started(), this will first call stop() */
149  using Component::uninit;
150 
151  //! Get the remaining arguments that were not parsed by the command line
152  /*! Any command line arguments after a lone '--' will be available in remainingArgs() */
153  std::vector<std::string> const & remainingArgs() const;
154 
155  //! @}
156 
157  protected:
158  // BEGIN_JEVOIS_CODE_SNIPPET manager2.C
159 
160  //! Parameter callback
161  void onParamChange(manager::loglevel const & param, manager::LogLevel const & newval);
162 
163  //! Parameter callback
164  void onParamChange(manager::tracelevel const & param, unsigned int const & newval);
165  // END_JEVOIS_CODE_SNIPPET
166 
167  //! Calls parseCommandLine()
168  void preInit() override;
169 
170  //! Checks for the --help flag
171  void postInit() override;
172 
173  //! Constructs a help message from all parameters in the model, and outputs it to 'out'
174  void constructHelpMessage(std::ostream & out) const;
175 
176  //! Constructs a help message and tries to send it to /usr/bin/less
177  void printHelpMessage() const;
178 
179  private:
180  //! Parse the command line and internally store the resulting remaining args
181  void doParseCommandLine();
182 
183  //! Parses the command line, and applies settings to all Parameters
184  /*! See the definition of Parameter for details on how to specify them from the command line. */
185  std::vector<std::string> const parseCommandLine(std::vector<std::string> const & commandLineArgs);
186 
187  //! The original command line arguments
188  std::vector<std::string> itsCommandLineArgs;
189 
190  //! Did we get command-line args (even though there may be none, just to detect if forgot)
191  bool itsGotArgs;
192 
193  //! Any command line arguments not used by the model
194  std::vector<std::string> itsRemainingArgs;
195  };
196 } // namespace jevois
197 
198 // Include implementation details
std::shared_ptr< Comp > addComponent(std::string const &instanceName, Args &&...args)
Pseudo-constructor: construct a top-level Component.
Definition: ManagerImpl.H:26
void setCommandLineArgs(int argc, char const *argv[])
Set the command-line arguments, call this before start() if args were not passed at construction...
Definition: Manager.C:38
std::shared_ptr< Comp > getSubComponent(std::string const &instanceName) const =delete
Use getComponent() on the Manager as opposed to jevois::Component::getSubComponent() ...
Generic variadic template class template definition for Component Parameters.
JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(l2grad, bool,"Use more accurate L2 gradient norm if true, L1 if false", false, ParamCateg)
void preInit() override
Calls parseCommandLine()
Definition: Manager.C:49
Manager of a hierarchy of Component objects.
Definition: Manager.H:66
JEVOIS_DECLARE_PARAMETER(thresh1, double,"First threshold for hysteresis", 50.0, ParamCateg)
A category to which multiple ParameterDef definitions can belong.
Definition: ParameterDef.H:33
void printHelpMessage() const
Constructs a help message and tries to send it to /usr/bin/less.
Definition: Manager.C:76
void onParamChange(manager::loglevel const &param, manager::LogLevel const &newval)
Parameter callback.
A component of a model hierarchy.
Definition: Component.H:176
void removeComponent(std::shared_ptr< Comp > &component)
Remove a top-level Component from the Manager, by shared_ptr.
Definition: ManagerImpl.H:100
std::vector< std::string > const & remainingArgs() const
Get the remaining arguments that were not parsed by the command line.
Definition: Manager.C:168
void removeSubComponent(std::shared_ptr< Comp > &component)=delete
Use removeComponent() on the Manager as opposed to jevois::Component::removeSubComponent() ...
std::string const & instanceName() const
The instance name of this component.
Definition: Component.C:48
std::shared_ptr< Comp > getComponent(std::string const &instanceName) const
Get a top-level component by instance name.
Definition: ManagerImpl.H:60
void postInit() override
Checks for the –help flag.
Definition: Manager.C:58
void constructHelpMessage(std::ostream &out) const
Constructs a help message from all parameters in the model, and outputs it to 'out'.
Definition: Manager.C:82
std::shared_ptr< Comp > addSubComponent(std::string const &instanceName, Args &&...args)=delete
Use addComponent() on the Manager as opposed to jevois::Component::addSubComponent() ...
virtual ~Manager()
Destructor.
Definition: Manager.C:45
Manager(std::string const &instance="TheManager")
Constructor without command-line args.
Definition: Manager.C:27