MIRA
Framework.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2012 by
3  * MetraLabs GmbH (MLAB), GERMANY
4  * and
5  * Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
6  * All rights reserved.
7  *
8  * Contact: info@mira-project.org
9  *
10  * Commercial Usage:
11  * Licensees holding valid commercial licenses may use this file in
12  * accordance with the commercial license agreement provided with the
13  * software or, alternatively, in accordance with the terms contained in
14  * a written agreement between you and MLAB or NICR.
15  *
16  * GNU General Public License Usage:
17  * Alternatively, this file may be used under the terms of the GNU
18  * General Public License version 3.0 as published by the Free Software
19  * Foundation and appearing in the file LICENSE.GPL3 included in the
20  * packaging of this file. Please review the following information to
21  * ensure the GNU General Public License version 3.0 requirements will be
22  * met: http://www.gnu.org/copyleft/gpl.html.
23  * Alternatively you may (at your option) use any later version of the GNU
24  * General Public License if such license has been publicly approved by
25  * MLAB and NICR (or its successors, if any).
26  *
27  * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
28  * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
29  * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
30  * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  *
32  * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
33  * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
34  * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
35  * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
36  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
37  */
38 
48 #ifndef _MIRA_FRAMEWORK_H_
49 #define _MIRA_FRAMEWORK_H_
50 
51 #include <serialization/adapters/std/list>
52 #include <serialization/adapters/std/map>
53 #include <serialization/adapters/boost/shared_ptr.hpp>
54 
55 #include <utils/ProgramOptions.h>
56 #include <platform/Types.h>
57 #include <rpc/RPCManager.h>
58 #include <thread/ScopedAccess.h>
59 #include <utils/Singleton.h>
60 #include <xml/XMLDomReflect.h>
61 #include <xml/XMLDomModifier.h>
63 #include <thread/ThreadMonitor.h>
64 
65 #include <fw/Authority.h>
66 #include <fw/AuthorityManager.h>
67 #include <fw/Channel.h>
68 #include <fw/ChannelManager.h>
69 #include <fw/NameRegistry.h>
70 
71 #include <loader/Loader.h>
72 
74 #define MIRA_FW mira::Framework::instance()
75 
76 namespace mira {
77 
79 
80 // forward decls.
81 struct IntSignal;
82 class ErrorService;
83 class Framework;
84 class FrameworkTransformer;
85 class RemoteModule;
86 class UnitManager;
87 
89 namespace Private {
90 
92 
100 class MIRA_FRAMEWORK_EXPORT FrameworkStartup
101 {
102 public:
103  FrameworkStartup(int argc, char** argv);
104  FrameworkStartup(const std::vector<std::string>& args);
105 
106 protected:
107 
108  void initialize();
109  ProgramOptions mOptions;
110  typedef std::vector<std::string> CommandLineStrings;
111  CommandLineStrings mCommandLineVariables;
112  CommandLineStrings mCommandLineKnownFrameworks;
113 };
114 
116 
117 class FrameworkAuthority : public Authority
118 {
119 public:
120  FrameworkAuthority(Framework* framework, const ResourceName& ns,
121  const std::string& name, Flags flags = Authority::NORMAL)
122  : Authority(ns, name, flags), mFramework(framework)
123  {}
124 
125 public:
126  boost::shared_ptr<PropertyNode> getProperties();
127 
128 protected:
129  Framework* mFramework;
130 };
131 
133 
134 }
136 
138 
150 class MIRA_FRAMEWORK_EXPORT Framework : public Private::FrameworkStartup,
151  public ExplicitSingleton<Framework>
152 {
153 public:
154 
162  Framework(int argc, char** argv, bool startImmediately = false);
169  Framework(const std::vector<std::string>& args, bool startImmediately = false);
170 
171  virtual ~Framework();
172 
174  template<typename Reflector>
175  void reflect(Reflector& r)
176  {
177  serialization::VersionType version = r.version(2, this);
178 
179  if (version >= 2)
180  r.property("RemoteModule", mRemoteModule, "The remote module", boost::shared_ptr<RemoteModule>());
181 
182  r.method("getUptime", &Framework::getUptime, this, "Get the time since the framework was started");
183 
184  r.method("terminateProcess", &Framework::requestTermination, this,
185  "Terminate framework (and thus, the process). Use with care!",
186  "exitcode", "the exitcode returned by the process", 0u);
187 
188  r.interface("IVariableRegistry");
189  r.method("getVariables", &Framework::getVariables, this,
190  "Query variables");
191 
192  r.interface("ILibraryRegistry");
193  r.method("getLibraries",
195  "Query libraries");
196  r.method("getLoadedLibraries",
197  boost::function<LibraryRegistry::Register()>([](){
199  for (auto it = reg.begin(); it != reg.end(); ) {
200  if (it->second.mIsLoaded)
201  ++it;
202  else {
203  auto succ = it; ++succ;
204  reg.erase(it);
205  it = succ;
206  }
207  }
208  return reg;
209  }),
210  "Query only loaded libraries");
211 
212  r.interface("IConfigurationLoader");
213  r.method("loadConfig",
214  boost::function<void(const XMLDom&)>(
215  [&](const XMLDom& xml) { this->load(const_cast<XMLDom&>(xml)); } ),
216  "Load a configuration",
217  "xml", "XML document", XMLDom());
218 
219  r.interface("IThreadMonitor");
220  r.method("getThreadInformation",
221  boost::function<ThreadMonitor::BasicThreadInfoVector()>(
222  [] { return ThreadMonitor::instance().getBasicThreadInformation(); } ),
223  "Query thread information");
224 
225  }
226 
227 public:
228  boost::shared_ptr<PropertyNode> getProperties() {
229  return mProperties;
230  }
231 
232 public:
233 
240  void load(XMLDom& xml);
241 
248  void load(const std::string& configFile);
249 
254  void load();
255 
260  void start();
261 
265  bool isStarted() const
266  {
267  return mIsStarted;
268  }
269 
274  {
275  return Time::now() - mStartTime;
276  }
277 
283  virtual int exec();
284 
293  virtual void requestTermination(int exitcode=0);
294 
298  virtual bool isTerminationRequested() const;
299 
305  int getTerminationExitCode() const;
306 
315  int run();
316 
317 public:
318 
321 
323  NameRegistry& getNameRegistry() { return mNames; }
324 
326  AuthorityManager& getAuthorityManager() { return mAuthorityManager; }
327 
329  ChannelManager& getChannelManager() { return mChannelManager; }
330 
332  boost::shared_ptr<FrameworkTransformer> getTransformer() { return mTransformer; }
333 
335  ConfigurationLoader& getConfigurationLoader() { return mConfigurationLoader; }
336 
338  boost::shared_ptr<UnitManager> getUnitManager() { return mUnitManager; }
339 
341  RPCManager& getRPCManager() { return mRPCManager; }
342 
344  boost::shared_ptr<ErrorService> getErrorService() { return mErrorServiceModule; }
345 
347  boost::shared_ptr<RemoteModule> getRemoteModule() { return mRemoteModule; }
348 
350 
356  std::string getID() const { return mAuthority->getID(); }
357 
362  std::string getGlobalID() const { return mAuthority->getGlobalID(); }
363 
368  XMLVariablesMap& getVariables() { return mXMLPreprocessor.variables; }
369 
370  XMLDomPreprocessor& getXMLDomPreprocessor() { return mXMLPreprocessor; }
371 
378  {
379  return ScopedAccess<ProtecteeDatabase>(&mMetaDatabase);
380  }
381 
382  bool isInExec() const { return mInExec; }
383 
384 protected:
385 
386  friend class Private::FrameworkStartup;
387 
388  void initialize();
389  void finalize();
390  void ctrlCHandler(const IntSignal& sig);
391 
392  static void errorHandler(const IntSignal& sig);
393  static bool enterLeaveErrorHandler(bool enter);
394 
395 protected:
396 
400  bool mInExec;
402 
403  // The authority of the framework (used for all services of the framework
404  // as well as providing a process thread for submodules)
405  boost::shared_ptr<Private::FrameworkAuthority> mAuthority;
406 
408  boost::shared_ptr<PropertyNode> mProperties;
409 
410  // our components:
412  boost::shared_ptr<RemoteModule> mRemoteModule;
413 
414  // DO NOT CHANGE THE ORDER of the following components, the order of
415  // destruction is important for producing correct error messages when
416  // destroying the framework and errors occur. If the order is not correct,
417  // it could result in misleading error messages.
418  RPCManager mRPCManager; // create RPCManager and ChannelManager first
419  ChannelManager mChannelManager; // to bring up the communication components
420  // that may be used by the components below.
422  boost::shared_ptr<FrameworkTransformer> mTransformer;
423 
424  boost::shared_ptr<UnitManager> mUnitManager;
425 
427 
428  boost::shared_ptr<ErrorService> mErrorServiceModule;
429  std::string mName;
430 
434 
436 };
437 
439 
440 }
441 
442 #include <fw/impl/Authority.hpp>
443 #include <fw/impl/ConcreteChannel.hpp>
444 
445 #endif
Authority class that is used to access the functionality of the framework.
XMLDom mConfigDom
Definition: Framework.h:432
void reflect(Reflector &r)
Reflect method for serialization.
Definition: Framework.h:175
A STL conform wrapper for libxml2 to read XML files as DOM.
Definition: XMLDom.h:73
Typedefs for OS independent basic data types.
std::string mName
Definition: Framework.h:429
boost::shared_ptr< ErrorService > getErrorService()
Returns the pointer to the persistent error service.
Definition: Framework.h:344
Manager class for all framework channels.
std::string getGlobalID() const
Return the fully qualified global id of this framework (includes namespace)
Definition: Framework.h:362
Normally authorities must have a unique name.
Definition: Authority.h:104
Manager class for all authorities in a framework.
ConfigurationLoader & getConfigurationLoader()
Returns the reference to the configuration file loader.
Definition: Framework.h:335
static Type & instance()
Returns a reference to the singleton instance.
Definition: Singleton.h:544
bool mInExec
Definition: Framework.h:400
boost::shared_ptr< FrameworkTransformer > getTransformer()
Returns the pointer to the transform framework.
Definition: Framework.h:332
specialize cv::DataType for our ImgPixel and inherit from cv::DataType<Vec>
Definition: IOService.h:67
A thread monitor, which collects information about the resources of all running threads of the curren...
std::vector< BasicThreadInfo > BasicThreadInfoVector
Vector of serializable thread info.
Definition: ThreadMonitor.h:236
Only for backward compatibility.
Stores aliases for namespaces and allows to resolve local names to global fully qualified names...
Definition: NameRegistry.h:66
Grants thread-safe access to an object (the Protectee) that should be protected from concurrent acces...
Definition: ScopedAccess.h:119
boost::shared_ptr< ErrorService > mErrorServiceModule
Definition: Framework.h:428
int mTerminationExitCode
Definition: Framework.h:398
ConfigurationLoader mConfigurationLoader
Definition: Framework.h:426
Structure used in signal handlers to pass the signal and callstack.
Definition: SignalHandler.h:67
uint8 VersionType
Definition: ReflectorInterface.h:72
std::string getID() const
Returns the ID of this framework.
Definition: Framework.h:356
bool mTerminationRequested
Definition: Framework.h:397
Wrapper class for boost::posix_time::ptime for adding more functionality to it.
Definition: Time.h:418
RootPropertyNode mPropertiesRoot
Definition: Framework.h:407
class MIRA_FRAMEWORK_EXPORT Authority
forward declaration
Definition: RemoteConnection.h:74
Configuration loader for loading XML application configuration files.
bool isInExec() const
Definition: Framework.h:382
Duration getUptime() const
Return duration since started.
Definition: Framework.h:273
std::map< std::string, LibraryInfo > Register
Definition: LibraryRegistry.h:119
Registry for shared libraries.
AuthorityManager mAuthorityManager
Definition: Framework.h:421
bool isStarted() const
Return true if framework is started.
Definition: Framework.h:265
bool mRemoteDisabled
Definition: Framework.h:401
ProtecteeMixin< MetaTypeDatabase > ProtecteeDatabase
Definition: Framework.h:372
ChannelManager mChannelManager
Definition: Framework.h:419
Resolving names of channels and authorities in namespaces.
boost::shared_ptr< RemoteModule > mRemoteModule
Definition: Framework.h:412
bool mIsStarted
Definition: Framework.h:399
#define MIRA_FRAMEWORK_EXPORT
Definition: FrameworkExports.h:61
A singleton class that can be freely configured using policies that control the creation, instantiation, lifetime and thread-safety.
Use this class to represent time durations.
Definition: Time.h:106
This class represents the core element of a modular application.
Definition: Framework.h:150
A special node that acts only as (empty) root node for a property tree.
Definition: PropertyNode.h:448
std::map< std::string, XMLVariableValue > XMLVariablesMap
Definition: XMLDomPreprocessor.h:91
ProtecteeDatabase mMetaDatabase
Definition: Framework.h:433
ScopedAccess< ProtecteeDatabase > getMetaDatabase()
Return the meta database that contains all known meta information in this framework.
Definition: Framework.h:377
RPCManager & getRPCManager()
Returns the reference to the manager singleton for registered RPC services.
Definition: Framework.h:341
virtual void requestTermination(int exitcode=0)
Requests the termination of the framework and hence the whole application.
boost::shared_ptr< UnitManager > mUnitManager
Definition: Framework.h:424
Provided for convenience.
Definition: Singleton.h:580
boost::shared_ptr< PropertyNode > getProperties()
Definition: Framework.h:228
boost::shared_ptr< FrameworkTransformer > mTransformer
Definition: Framework.h:422
boost::shared_ptr< Private::FrameworkAuthority > mAuthority
Definition: Framework.h:405
Framework channel classes.
NameRegistry & getNameRegistry()
Returns the reference to the name registry.
Definition: Framework.h:323
AuthorityManager & getAuthorityManager()
Returns the reference to the manager singleton for registered authorities.
Definition: Framework.h:326
ChannelManager & getChannelManager()
Returns the reference to the manager singleton for channels.
Definition: Framework.h:329
XMLDomPreprocessor & getXMLDomPreprocessor()
Definition: Framework.h:370
Central instance that stores all created Authorities.
Definition: AuthorityManager.h:130
Preprocesses XML documents and resolves all special tags like , <if>, <warning> and so on...
Definition: XMLDomPreprocessor.h:106
Time mStartTime
Definition: Framework.h:435
boost::shared_ptr< RemoteModule > getRemoteModule()
Returns the pointer to the remote module.
Definition: Framework.h:347
Class for accessing command line parameters.
Contains internal RPCManager class.
XMLVariablesMap & getVariables()
Returns the list of variables that are registered via command line or config file.
Definition: Framework.h:368
static Time now() static Time eternity()
Returns the current utc based time.
Definition: Time.h:481
NameRegistry mNames
Definition: Framework.h:411
boost::shared_ptr< UnitManager > getUnitManager()
Returns the reference to the unit manager.
Definition: Framework.h:338
An exception that occurred whenever a channel does not exist.
Definition: ChannelManager.h:75
Grants thread-safe access to an object that should be protected from concurrent access.
XMLDomPreprocessor mXMLPreprocessor
Definition: Framework.h:431
boost::shared_ptr< PropertyNode > mProperties
Definition: Framework.h:408
This class is for internal use only.
Definition: RPCManager.h:96
Class for loading, parsing, modifying and interpreting application configuration files.
Definition: Loader.h:181
static Register getRegister()
Get access to library register.
Definition: LibraryRegistry.h:145
RPCManager mRPCManager
Definition: Framework.h:418
Contains non-intrusive reflects for XMLDom documents.