iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Connector.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_CONNECTOR_H
37 #define INCLUDE_NRT_CORE_BLACKBOARD_CONNECTOR_H
38 
40 
41 namespace nrt
42 {
43  // ######################################################################
44  /*! \defgroup connector Connector classes and functions
45 
46  Connector objects allow messages to be passed across namespaces (aka macro-modules) or within namespaces (with,
47  e.g., a topic translation). The messages are not changed in any way, Connector objects just help establishing
48  connections between actual module ports. Messages do not actually transit through the connectors; instead,
49  connectors just connect together ports that woud not otherwise be connected, but once connected, the passing of
50  messages is direct between module ports.
51 
52  Most users do not need to worry about Connectors, those are just the funny ports that appear on macro-modules.
53 
54  Connectors cannot be accessed or used directly. They are created on the Master Blackboard only. To manipulate
55  them, use the connector-related functions of the Blackboard class.
56 
57  \ingroup blackboard */
58 
59  /*! @{ */ // **********************************************************************
60 
61  // ######################################################################
62  //! MessagePosterConnector class defines a connector for a MessagePoster
63  /*! MessagePosterConnector has an input port (subscription) that can catch posts with matching message type, return
64  type, namespace, and topic, and an output port (posting) onto which any received messages will be re-posted, but
65  using that output port's topic, and either in the same namespace or in the parent namespace (if border
66  connector). Note that connectors do not actually catch messages and re-post them, they are just an abstraction for
67  this catching and re-posting, but these actions are transparently handled by the Blackboard with no need for any
68  message to actually transition through the connector object. Instead, when some connected path is found by the
69  Blackboard between a MessagePoster and a MessageSubscriber with any number of possibly intervening connectors
70  where all namespaces and topics correctly mesh with each other, then the Blackboard directly forwards all messages
71  posted by the MessagePoster to the MessageSubscriber.
72 
73  Example use is:
74 
75  ModuleA posts onto topic1
76  ModuleB posts onto topic2
77 
78  you create a MessagePosterConnector and setTopicFilter("topic[12]") and setTopic("cooltopic"). As a result, any
79  message posted by ModuleA or ModuleB will be sent to any subscriber that catches cooltopic. This is particularly
80  useful when the ConnectorType is Border, in shich case, subscribers in the parent namespace from that of ModuleA,
81  ModuleB and the connector will receive the messages. */
82  template <class Posting>
84  {
85  public:
86  //! Public destructor so std::shared_ptr<...> can delete the Connector
87  virtual ~MessagePosterConnector();
88 
89  private:
90  //! Construct a poster connector
91  MessagePosterConnector(std::string const & instanceId = "", std::string const & namespc = "",
92  ConnectorType const type = ConnectorType::Intra, std::string const & topicfilt = "",
93  std::string const & topic = "");
94 
95  //! Only the BlackboardMaster can manipulate us directly
96  friend class BlackboardMaster;
97  };
98 
99  // ######################################################################
100  //! MessageCheckerConnector class defines a connector for a MessageChecker
101  template <class Checking>
103  {
104  public:
105  //! Public destructor so std::shared_ptr<...> can delete the Connector
106  virtual ~MessageCheckerConnector();
107 
108  private:
109  //! Construct a checker connector
110  MessageCheckerConnector(std::string const & instanceId = "", std::string const & namespc = "",
111  ConnectorType const type = ConnectorType::Intra, std::string const & topic = "",
112  std::string const & topicfilt = "");
113 
114  //! Only the BlackboardMaster can manipulate us directly
115  friend class BlackboardMaster;
116  };
117 
118  // ######################################################################
119  //! MessageSubscriberConnector class defines a connector for a MessageSubscriber
120  template <class Subscription>
122  {
123  public:
124  //! Public destructor so std::shared_ptr<...> can delete the Connector
125  virtual ~MessageSubscriberConnector();
126 
127  private:
128  //! Construct a subscriber connector
129  MessageSubscriberConnector(std::string const & instanceId = "", std::string const & namespc = "",
130  ConnectorType const type = ConnectorType::Intra, std::string const & topic = "",
131  std::string const & topicfilt = "");
132 
133  //! Only the BlackboardMaster can manipulate us directly
134  friend class BlackboardMaster;
135  };
136 
137  /*! @} */ // **********************************************************************
138 
139 }; // namespace nrt
140 
141 // Include inlined implementation details that are of no interest to the end user
144 
145 #endif // INCLUDE_NRT_CORE_BLACKBOARD_CONNECTOR_H