iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
BlackboardManager.H
Go to the documentation of this file.
1 /*! @file
2  @author Laurent Itti
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 
36 #ifndef INCLUDE_NRT_CORE_BLACKBOARD_BLACKBOARDMANAGER_H
37 #define INCLUDE_NRT_CORE_BLACKBOARD_BLACKBOARDMANAGER_H
38 
39 #include <nrt/Core/Model/Manager.H>
40 #include <thread>
41 
42 namespace nrt
43 {
44  // ######################################################################
45  /*! \defgroup bbmanager Blackboard Manager class and related messages
46 
47  The BlackboardManager is a Component that allows users to configure the Blackboard, for example setting the master
48  IP address and port, etc.
49 
50  \ingroup blackboard */
51 
52  //! Namespace for parameters and ports of the BlackboardManager
53  /*! \ingroup bbmanager */
54  namespace blackboardmanager
55  {
56  // ######################################################################
57  /*! \defgroup BlackboardParameters BlackboardManager Configuration Parameters
58  \ingroup bbmanager */
59  //! @{
60  static nrt::ParameterCategory const BlackboardParamCateg("Blackboard Related Options");
61 
62  NRT_DECLARE_PARAMETER(masterip, std::string,
63  "The IP address or hostname of the master Blackboard. The default empty string will "
64  "try to extract this value from the $NRTMASTER environment variable.",
65  "",
66  BlackboardParamCateg);
67 
68  NRT_DECLARE_PARAMETER(masterport, int,
69  "The port of the master Blackboard, or 0 to discover and use the first available open "
70  "port. The default of -1 will try to extract the port from the $NRTMASTER environment "
71  "variable.",
72  -1,
73  BlackboardParamCateg);
74 
75  NRT_DECLARE_PARAMETER(master, bool,
76  "Set this blackboard as the master node if true",
77  false,
78  BlackboardParamCateg);
79 
80  NRT_DECLARE_PARAMETER_WITH_CALLBACK(nick, std::string,
81  "Optional nickname for this Blackboard, will be set to the hostname if empty",
82  "",
83  BlackboardParamCateg);
84  //! @}
85  }
86 
87  // ######################################################################
88  //! The BlackboardManager component can be inserted into an nrt::Manager hierarchy to expose Blackboard options
89  /*! Users are strongly encouraged to create a BlackboardManager Component in every executable to expose some crucial
90  parameters for configuring the global Blackboard, such as the network address of the master Blackboard, etc. See
91  the \link BlackboardParameters Blackboard Parameters\endlink for more details.
92 
93  Note that when and only when BlackboardManager is in initialized state, the Blackboard is in operational
94  state.
95 
96  \ingroup bbmanager */
98  public nrt::Parameter<blackboardmanager::masterip,
99  blackboardmanager::masterport,
100  blackboardmanager::master,
101  blackboardmanager::nick>
102  {
103  public:
104  //! Constructor
105  BlackboardManager(std::string const & instanceName = "Blackboard");
106 
107  //! Destructor
108  virtual ~BlackboardManager();
109 
110  //! \name Blackboard federation runstate management
111  //! @{
112 
113  //! Initialization
114  /*! Dispatches the command to the entire Blackboard federation. Note that init() is usually handled locally by
115  each Blackboard so you should typically not have to use this. */
116  void fedinit();
117 
118  //! Starts the component, and its subtree, recursively
119  /*! Dispatches the command to the entire Blackboard federation */
120  void fedstart();
121 
122  //! Launch the run() function, and propagate to subcomponents
123  /*! Dispatches the command to the entire Blackboard federation */
124  void fedlaunch();
125 
126  //! Switch out of running state and then call waitendrun() to wait for all run() threads to complete
127  /*! Dispatches the command to the entire Blackboard federation */
128  void fedendrun();
129 
130  //! Stops the component and its subtree, recursively
131  /*! Dispatches the command to the entire Blackboard federation */
132  void fedstop();
133 
134  //! Un-initialize
135  /*! Dispatches the command to the entire Blackboard federation. You would normally not use this as each Blackboard
136  typically handles uninit() locally. */
137  void feduninit();
138  //! @}
139 
140  //! \name Local blackboard runstate management
141  //! @{
142 
143  //! Set our runstate up/down to match the Blackboard federation master
144  /*! Use this after everything is ready to go in apps that may join a running party. For example, nrDesigner uses
145  this function so its start/stop button is correctly displayed even when the designer joins a federation that
146  may or may not already be running(). */
147  void setRunStateFromMaster();
148 
149  //! Local initialization
150  virtual void init();
151 
152  //! Local start
153  /*! See Component.H for explanations about run states. */
154  virtual void start();
155 
156  //! Local launch
157  /*! See Component.H for explanations about run states. */
158  virtual void launch();
159 
160  //! Local endrun
161  /*! See Component.H for explanations about run states. */
162  virtual void endrun();
163 
164  //! Local stop
165  /*! See Component.H for explanations about run states. */
166  virtual void stop();
167 
168  //! Local un-init
169  /*! See Component.H for explanations about run states. */
170  virtual void uninit();
171 
172  //! @}
173 
174  protected:
175  void preInit();
176 
177  void preStop();
178 
179  void onParamChange(nrt::blackboardmanager::nick const & param, std::string const & newval);
180 
181  //! Protect init()/start()/etc
182  mutable boost::shared_mutex itsRunStateMtx;
183  };
184 }; // namespace nrt
185 
186 #endif // INCLUDE_NRT_CORE_BLACKBOARD_BLACKBOARDMANAGER_H