iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
BlackboardFederationSummary.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 #ifndef INCLUDE_NRT_CORE_BLACKBOARD_BLACKBOARDFEDERATIONSUMMARY_H
36 #define INCLUDE_NRT_CORE_BLACKBOARD_BLACKBOARDFEDERATIONSUMMARY_H
37 
40 #include <string>
41 #include <vector>
42 #include <map>
43 #include <iosfwd>
44 
45 namespace nrt
46 {
47  namespace blackboard
48  {
49  /*! \defgroup bfsummary Blackboard Federation summary data
50 
51  The BlackboardFederationSummary is updated and broadcast to all Blackboards each type new modules, posrts, etc
52  are added to the federation.
53 
54  \ingroup blackboard */
55 
56  /*! @{ */ // **********************************************************************
57 
58  // ######################################################################
59  //! Summary about a BlackboardManager
61  {
62  std::string bbnick; //!< The Blackboard nickname
63  std::string hostname; //!< The Blackboard's hostname
64  bool ismaster; //!< Is this Blackboard the federation master?
65  std::string masterip; //!< The IP address or hostname of the master for this Blackboard
66  int masterport; //!< The port number of the master for this Blackboard
67  bool isloader; //!< True if Blackboard has a ModuleLibrary and can load modules from it
68  bool hasnethandler; //!< True if Blackboard has a network handler
69  bool hashttpbridge; //!< True if Blackboard has an TTP bridge
70 
71  //! Serialization
72  template <class Archive> void serialize(Archive & ar)
74  };
75 
76  //! Output stream operator overload (mostly for debug messages)
77  std::ostream & operator<<(std::ostream & os, nrt::blackboard::BlackboardManagerSummary const & bbms);
78 
79  // ######################################################################
80  //! Summary about a Module Port, for sharing across the Blackboard Federation
82  {
83  //! Default constructor
85 
86  //! Constructor
87  ModulePortSummary(std::string const & msgtype_, std::string const & rettype_, std::string const & portname_,
88  std::string const & description_, std::string const & topi_, bool const splittable_,
89  bool const issplit_);
90 
91  std::string msgtype; //!< Type of Message
92  std::string rettype; //!< Type of Return Message (empty if Checking)
93  std::string portname; //!< String class name for the port
94  std::string description; //!< String human description for the port
95  std::string topi; //!< Topic or topic filter for the port
96  bool splittable; //!< Can this port be split into sub-ports?
97  bool issplit; //!< Is this port currently split into sub-ports?
98 
99  //! Serialization
100  template <class Archive> void serialize(Archive & ar)
102  };
103 
104  //! Output stream operator overload (mostly for debug messages)
105  std::ostream & operator<<(std::ostream & os, nrt::blackboard::ModulePortSummary const & mps);
106 
107  // ######################################################################
108  //! Summary about a Module, for sharing across the Blackboard Federation
110  {
111  //! Default constructor
112  ModuleSummary(); // needed by serialization
113 
114  //! Constructor
115  ModuleSummary(std::string const & logicalpath_, std::string const & instance_, std::string const & parent_);
116 
117  std::string logicalpath; //!< Logical path of the module, as categ/subcat/.../classname
118  std::string instance; //!< User supplied instance name of the particular module
119  std::string parent; //!< Module UID of the nearest parent module, or empty
120 
121  std::vector<ModulePortSummary> posters; //!< Summary info about all this module's MessagePoster ports
122  std::vector<ModulePortSummary> checkers; //!< Summary info about all this module's MessageChecker ports
123  std::vector<ModulePortSummary> subscribers; //!< Summary info about all this module's MessageSubscriber ports
124 
125  //! Serialization
126  template <class Archive> void serialize(Archive & ar)
128  };
129 
130  //! Output stream operator overload (mostly for debug messages)
131  std::ostream & operator<<(std::ostream & os, nrt::blackboard::ModuleSummary const & ms);
132 
133  // ######################################################################
134  //! Summary about a Connector, for sharing across the Blackboard Federation
136  {
137  //! Default constructor
138  ConnectorSummary(); // needed by serialization
139 
140  //! Constructor
141  ConnectorSummary(std::string const & msgtype_, std::string const & rettype_, std::string const & instance_,
142  ConnectorType const type_, std::string const & topic_, std::string const & topicfilt_);
143 
144  std::string msgtype; //!< The outgoing message type
145  std::string rettype; //!< The return type
146  std::string instance; //!< The instance name
147  ConnectorType type; //!< The type of connector
148  std::string topic; //!< The topic
149  std::string topicfilt; //!< The topic filter
150 
151  //! Serialization
152  template <class Archive> void serialize(Archive & ar)
154  };
155 
156  //! Output stream operator overload (mostly for debug messages)
157  std::ostream & operator<<(std::ostream & os, nrt::blackboard::ConnectorSummary const & cs);
158 
159  // ######################################################################
160  //! Summary about a connection between two modules
162  {
163  //! Default constructor
164  ConnectionSummary(); // needed by serialization
165 
166  //! Constructor
167  ConnectionSummary(std::string const & bbuid1_, std::string const & module1_, std::string const & portname1_,
168  std::string const & bbuid2_, std::string const & module2_, std::string const & portname2_);
169 
170  std::string bbuid1; //!< Blackboard UID of module/connector 1
171  std::string module1; //!< Module/connector 1 uid
172  std::string portname1; //!< String class name of side 1 port if module; "topic" or "topicfilt" if connector
173  std::string bbuid2; //!< Blackboard UID of module/connector 2
174  std::string module2; //!< Module/connector 2 uid
175  std::string portname2; //!< String class name of side 2 port if module; "topic" or "topicfilt" if connector
176 
177  //! Serialization
178  template<class Archive> void serialize(Archive & ar)
180  };
181 
182  //! Output stream operator overload (mostly for debug messages)
183  std::ostream & operator<<(std::ostream & os, nrt::blackboard::ConnectionSummary const & cs);
184 
185  // ######################################################################
186  //! Summary information about a macro-module
188  {
189  //! Default constructor; modified is marked true by default
191 
192  //! Constructor
193  MacroModuleSummary(bool const modified_, std::string const & logicalpath_,
194  std::map<std::string, std::string> const & bbnickremap_);
195 
196  //! Whether the contents of this macro-module have been modified and will need saving
197  bool modified;
198 
199  //! Logical path of the macro-module
200  std::string logicalpath;
201 
202  //! Remapping of bbnicks between what was saved in file and how the macro-module was instantiated
203  std::map<std::string /* file bbnick */, std::string /* used bbnick */> bbnickremap;
204 
205  //! Serialization
206  template<class Archive> void serialize(Archive & ar)
207  { ar(modified, logicalpath, bbnickremap); }
208  };
209 
210  //! Output stream operator overload (mostly for debug messages)
211  std::ostream & operator<<(std::ostream & os, nrt::blackboard::MacroModuleSummary const & mms);
212 
213  // ######################################################################
214  //! Summary info about a namespace and what it contains
216  {
217  //! Macro-module summary for this namespace
219 
220  //! Modules and connectors inside this namespace:
221  std::map<std::string /* bbuid */, std::map<std::string /* module */, ModuleSummary> > modules;
222 
223  std::map<std::string /* connec */, ConnectorSummary> pconnectors;
224  std::map<std::string /* connec */, ConnectorSummary> cconnectors;
225  std::map<std::string /* connec */, ConnectorSummary> sconnectors;
226 
227  //! Connections within this namespace:
228  std::vector<ConnectionSummary> connections;
229 
230  //! Access the parent namespace, or nullptr if we are the root
232 
233  //! Access/create a subnamespace by providing relative namespace path
234  NamespaceSummary * subnamespace(std::string const & rnpath);
235 
236  //! Access a subnamespace by providing relative namespace path, throws if not found
237  NamespaceSummary const * getsubnamespace(std::string const & rnpath) const;
238 
239  //! Return true if the requested subnamespace exists
240  bool hassubnamespace(std::string const & rnpath) const;
241 
242  // Subnamespaces, recursively indexed by their relative name (just one level)
243  std::map<std::string /* relativenamespc */, std::shared_ptr<NamespaceSummary> > subnamespaces;
244 
245  //! Helper function to get the bbuid that holds a given moduleuid
246  /*! Throws if not found */
247  std::string const & bbuidForModule(std::string const & module) const;
248 
249  //! Recursively export everything in the summary as a python script
250  /*! \note Since parameters are not stored here, this requires a running federation and that all the modules in
251  the summayr are still alive and well, so we can contact their owner Blackboard and request a snapshot of all
252  their parameter values.
253 
254  For each namespace, a new file is written, and an import command for that file is added to the root file
255  (which should be opened and writeable). */
256  ////void exportPython(std::ostream & rootfile, std::string const & filestem, std::string const & nsname) const;
257  };
258 
259  // ######################################################################
260  //! Summary info about a federation of blackboards
262  {
263  //! Construct and allocate the root NamespaceSummary
265 
266  //! Virtual destructor for safe inheritance
268 
269  //! Mapping from Blackboard UIDs to their BlackboardManagerSummary
270  std::map<std::string /* bbuid */, BlackboardManagerSummary> bbms;
271 
272  //! List of pristine macro-modules (un-modified since loading, appear "locked" in the GUI)
273  std::map<std::string /* namespace */, std::string /* macromodule logical path */> macromodules;
274 
275  //! Modules, ports, connectors, and connections, organized by namespace
276  /*! By construction, nss is guaranteed to be initialized (not nullptr), since the root namespace always exists
277  (thus nss is allocated in the constructor of BlackboardFederationSummary, even if it is empty). */
278  std::shared_ptr<NamespaceSummary> nss;
279 
280  //! Helper function to get the bbuid that holds a given moduleuid
281  /*! Throws if not found */
282  std::string const & bbuidForModule(std::string const & module) const;
283 
284  //! Map from bbnick to bbuid
285  std::string const & bbuidForNick(std::string const & bbnick) const;
286 
287  //! Map from bbuid to bbnick
288  std::string const & bbnickForUID(std::string const & bbuid) const;
289 
290  //! Export everything in the summary as a python script
291  /*! \note Since parameters are not stored here, this requires a running federation and that all the modules in
292  the summayr are still alive and well, so we can contact their owner Blackboard and request a snapshot of all
293  their parameter values. */
294  ////void exportPython(std::string const & filestem) const;
295  };
296 
297  // ######################################################################
298  //! Helper function to translate bbnicks from file to instantiated (used for loading a file)
299  std::string const &
300  remapBBnickFileToInstance(std::string const & filebbnick,
301  std::map<std::string /* file bbnick */, std::string /* used bbnick */>
302  const & bbnickremap);
303 
304  //! Helper function to translate bbnicks from instantiated back to file (used for saving a file)
305  std::string const &
306  remapBBnickInstanceToFile(std::string const & instbbnick,
307  std::map<std::string /* file bbnick */, std::string /* used bbnick */>
308  const & bbnickremap);
309 
310  //! Compose two bbnick remappings
311  std::map<std::string /* file bbnick */, std::string /* used bbnick */>
312  composeBBnickRemaps(std::map<std::string /* file bbnick */, std::string /* used bbnick */> const & parent,
313  std::map<std::string /* file bbnick */, std::string /* used bbnick */> const & child);
314 
315  /*! @} */ // **********************************************************************
316  }
317 }
318 
319 #endif // INCLUDE_NRT_CORE_BLACKBOARD_BLACKBOARDFEDERATIONSUMMARY_H