iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
BlackboardMaster.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_BLACKBOARDMASTER_H
37 #define INCLUDE_NRT_CORE_BLACKBOARD_BLACKBOARDMASTER_H
38 
40 
41 namespace nrt
42 {
43  class HTTPBridge;
44 
45  //! Exra Blackboard functionality that exists on the Blackboard federation master only
46  /*! The Blackboard master should be the first oen to be created, and the last one to go out. Only the master can
47  create and manipulate namespaces and connectors, to ensure longest possible life and portability across load/save
48  of networks of modules over different federations of workers.
49 
50  This class is all private. Only its friends (the Blackboard class) can use it. External users should just use the
51  interface provided by the Blackboard class.
52 
53  \ingroup blackboard */
55  {
56  //! Allow Blackboard to use us
57  friend class Blackboard;
58 
59  //! Allow BlackboardManager to construct us
60  friend class BlackboardManager;
61 
62  //! Constructor
63  BlackboardMaster(int const port);
64 
65  //! Destructor
67 
68  // ######################################################################
69  // Namespace management
70  // ######################################################################
71 
72  //! Mutex to protect the namespaces
73  mutable boost::shared_mutex itsNsMtx;
74 
75  //! Create a namespace on a local or remote blackboard
76  void createNamespace(std::string const & namespc);
77 
78  //! Delete a namespace
79  void doLocalDeleteNamespace(std::string const & namespc);
80 
81  //! Rename a namespace and all its contents
82  void doLocalRenameNamespace(std::string const & oldnamespc, std::string const & newnamespc);
83 
84  //! Mark a namespace (macro-module) as modified, so that GUI will request user to save it
85  /*! Operations that modify the contents of a namespace call this automatically, so no need to call it in general,
86  unless you need to explicitly mark a namespace for saving even though no module, parameter, connection, etc
87  has been changed yet.
88 
89  \return true if the namespace was not previously already marked as modified */
90  bool markNamespaceModified(std::string const & namespc);
91 
92  //! Load a macro-module
93  std::string /* instance */
94  loadMacroModule(std::string const & logicalpath, std::string const & instancename, std::string const & namespc,
95  std::map<std::string /* file bbnick */, std::string /* used bbnick */> const & bbnickremap);
96 
97  //! Save a macro-module
98  void saveMacroModule(std::string const & namespc, nrt::ModuleManifest const & manifest) const;
99 
100  //! List of namespaces we own; we need this list to know about namespaces that are empty
101  /*! Namespaces will remain in the list until explicitly deleted. */
102  std::map<std::string /* namespc */, nrt::blackboard::MacroModuleSummary> itsNamespaces;
103 
104  // ######################################################################
105  // Connector management
106  // ######################################################################
107  //! Create a connector on the master Blackboard
108  /*! @return connector UID */
109  std::string
110  createConnector(nrt::ConnectorFlavor const flavor, std::string const & msgtype, std::string const & rettype,
111  std::string const & portname, std::string const & namespc, nrt::ConnectorType const type,
112  std::string const & topic, std::string const & topicfilt);
113 
114  //! Lookup a Connector UID from a namespace and instance name (portname) within that namespace
115  std::string getConnector(std::string const & namespc, std::string const & portname);
116 
117  //! Delete a connector on the master blackboard
118  void deleteConnector(std::string const & connuid);
119 
120  //! Set the topic on a local or remote connector
121  void setConnectorTopic(std::string const & connuid, std::string const & topic);
122 
123  //! Set the topic filter on a local or remote connector
124  void setConnectorTopicFilter(std::string const & connuid, std::string const & topicfilter);
125 
126  //! The set of all local Connectors that are currently alive and known
127  std::map<std::string /* connuid */,
128  std::shared_ptr<nrt::ConnectorBase> >
129  itsConnectors;
130 
131  mutable boost::shared_mutex itsConnMtx;
132 
133  // ######################################################################
134  // Module/macromodule (namespace) GUI coordinates managament
135  // ######################################################################
136 
137  // Shared mutex for all the GUI data
138  mutable boost::shared_mutex itsGuiMtx;
139 
140  //! Get GUI data for a given key of form m:ModuleUID, n:namespace, etc
141  nrt::blackboard::GUIdata getGUIdata(std::string const & key);
142 
143  //! Create/update GUI data for a given key of form m:ModuleUID or n:namespace
144  /*! \return true if some namespace was modified and a BFS update should be sent */
145  bool setGUIdata(std::string const & key, nrt::blackboard::GUIdata const & gd);
146 
147  //! Map of data for the GUI indexed by either: m:ModuleUID or [n|bp|bc|bs]:namespace
148  std::map<std::string /* indexkey */,
150  itsGUIdataMap;
151 
152  //! Register a new GUIdata listener
153  void registerRemoteGUIdataListener(std::string const & listenerbbuid);
154 
155  //! Un-Register a GUIdata listener
156  void unRegisterRemoteGUIdataListener(std::string const & listenerbbuid);
157 
158  //! On the master, list of bb's that have GUI data listeners
159  std::map<std::string /* bbuid */, size_t /* count */> itsRemoteGUIdataListeners;
160 
161  // ######################################################################
162  // HTTP Bridge to allow people to access us over HTTP
163  // ######################################################################
164  HTTPBridge * itsHTTPBridge; // on the master only
165 
166  // ######################################################################
167  // Blackboard federation updates
168  // ######################################################################
169  //! Let the distributed blackboard federation know about our interests (posts, checks, subscriptions, etc)
170  void doSendUpdateToBlackboardFederation(nrt::blackboard::BlackboardSummary & bs);
171 
172  //! Process update
173  void processSummaryUpdateFromBlackboardFederation
174  (std::shared_ptr<nrt::blackboard::BlackboardFederationSummary const> bfs,
175  std::set<std::string> const & alivebb);
176 
177  //! Recursively populate the GUI data in each sub-namespace
178  void populateGUIdata(std::shared_ptr<nrt::blackboard::NamespaceSummary> nss, std::string const & nsname,
179  std::set<std::string> & foundkeys);
180  };
181 
182 }
183 
184 #endif // INCLUDE_NRT_CORE_BLACKBOARD_BLACKBOARDMASTER_H