iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Parameter.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_MODEL_PARAMETER_H
37 #define INCLUDE_NRT_CORE_MODEL_PARAMETER_H
38 
42 #include <boost/thread.hpp>
43 
44 // Get our helpers
46 
47 // Declare a few types for MessagePoster, etc and ModuleParamPort
48 ////#include <nrt/Core/Blackboard/details/ModulePortHelpers.H>
49 
50 namespace nrt
51 {
52  class Component;
53 
54  /*! \defgroup parameter Component parameter-related classes and functions
55  \ingroup component */
56 
57  /*! @{ */ // **********************************************************************
58 
59  // ######################################################################
60  //! Base class for Parameter
61  /*! This exposes the string interface to the Parameter while derived template classes will expose the
62  value-based interface. */
64  {
65  public:
66  //! Constructor
67  ParameterBase();
68 
69  //! Destructor, will remove the parameter from its owner component
70  virtual ~ParameterBase();
71 
72  //! Get the parameter name. If you need more info about this parameter, try summary()
73  virtual std::string const & name() const = 0;
74 
75  //! Get the Component to which this Parameter is attached, or nullptr
76  Component * owner();
77 
78  //! Get the Component to which this Parameter is attached, or nullptr; const version
79  Component const * owner() const;
80 
81  //! Set the value from a string representation of it
82  /*! @throws nrt::exception::ParameterException if the given string cannot be converted (using boost::lexical_cast)
83  to a Parameter value, or the value is invalid according to our valid values spec. */
84  virtual void strset(std::string const & valstring) = 0;
85 
86  //! Get the value as a string representation of it
87  virtual std::string const strget() const = 0;
88 
89  //! Get summary info about this parameter
90  virtual ParameterSummary const summary() const = 0;
91 
92  //! Create a Module Port for this Parameter. See Module.H for more on Module.
93  ////virtual void createPort(ModuleParamPort const ptype, std::string const & module,
94  //// std::string const & descriptor) = 0;
95 
96  //! Delete a Module Port for this Parameter. See Module.H for more on Module.
97  ////virtual void deletePort(ModuleParamPort const ptype) = 0;
98 
99  //! Set the topic of a Parameter Poster
100  /*! Will throw if the port is not found, eg, it has not been created */
101  ////virtual void setPosterTopicP(std::string const & topic) = 0;
102 
103  //! Set the topic filter of a Parameter Checker
104  /*! Will throw if the port is not found, eg, it has not been created */
105  ////virtual void setCheckerTopicFilterP(std::string const & topicfilt) = 0;
106 
107  //! Set the topic filter of a Parameter Subscriber
108  /*! Will throw if the port is not found, eg, it has not been created */
109  ////virtual void setSubscriberTopicFilterP(std::string const & topicfilt) = 0;
110 
111  protected:
112  mutable boost::shared_mutex itsMutex; //!< Mutex to protect the parameter value
113  };
114 
115  /*
116  //! Simple CRTP struct for a Posting associated with a Parameter. See Module.H for details on posting.
117  template <typename T>
118  struct ParameterPosting : public nrt::MessagePosting<ParameterPosting<T>, nrt::Message<T>, void>
119  { static bool const requiresRunning = false; };
120 
121  //! Simple CRTP struct for a Checking associated with a Parameter. See Module.H for details on checking.
122  template <typename T>
123  struct ParameterChecking : public nrt::MessageChecking<ParameterChecking<T>, nrt::Message<T> >
124  { static bool const requiresRunning = false; };
125 
126  //! Simple CRTP struct for a Subscription associated with a Parameter. See Module.H for details on subscription.
127  template <typename T>
128  struct ParameterSubscription : public nrt::MessageSubscription<ParameterSubscription<T>, nrt::Message<T>, void>
129  {
130  //! Construct from a shared_ptr to a message
131  inline ParameterSubscription(std::shared_ptr<typename nrt::Message<T> const> msg) :
132  nrt::MessageSubscription<ParameterSubscription<T>, nrt::Message<T>, void>(msg) { };
133  static bool const requiresRunning = false;
134  };
135 
136  //! Subscriber helper class for parameter
137  template <typename T>
138  class ParameterMessageSubscriber : public nrt::MessageSubscriberCore<nrt::ParameterSubscription<T> >
139  {
140  public:
141  //! Type used for incoming messages in onMessage
142  typedef typename nrt::ParameterSubscription<T> InPtr;
143 
144  ParameterMessageSubscriber(nrt::ParameterCore<T> * param, std::string const & mod, std::string const & portna,
145  std::string const & descr);
146  virtual ~ParameterMessageSubscriber();
147 
148  virtual void onMessage(InPtr msg);
149 
150  private:
151  nrt::ParameterCore<T> * itsParam;
152  };
153  */
154  // ######################################################################
155  //! A changeable parameter for a Component, core class
156  /*! Parameters are used to expose user configurable settings for a Component. They can be specified from the command
157  line and will be set by the time Component::preStart() has been called on the Component which owns the Parameter.
158 
159  See examples in \link test-Component.C \endlink and \link test-Option.C \endlink */
160  template <typename T>
161  class ParameterCore : public ParameterBase
162  {
163  public:
164  //! Constructor
165  /*! \param def A pointer to the definition for this parameter (given by a ParameterDef). */
166  ParameterCore(ParameterDef<T> const & def);
167 
168  //! Destructor
169  virtual ~ParameterCore();
170 
171  //! Get the parameter name. If you need more info about this parameter, try summary()
172  virtual std::string const & name() const;
173 
174  //! Get the value of this Parameter
175  T get() const;
176 
177  //! Set the value of this Parameter
178  /*! Will throw nrt::exception::ParameterException if the new value is not accepted, in which case the old value
179  will remain in the Parameter. */
180  void set(T const & newVal);
181 
182  //! Set the value from a string representation of it
183  /*! @throws nrt::exception::ParameterException if the given string cannot be converted (using boost::lexical_cast)
184  to a valid Parameter value. */
185  virtual void strset(std::string const & valstring);
186 
187  //! Get the value as a string representation of it
188  virtual std::string const strget() const;
189 
190  //! Get summary info about this parameter
191  virtual ParameterSummary const summary() const;
192 
193  //! Create a Module Port for this Parameter. See Module.H for more on Module.
194  /*! \note This method will post() the current Parameter value as soon as the port is created */
195  //// virtual void createPort(ModuleParamPort const ptype, std::string const & module, std::string const & descriptor);
196 
197  //! Delete a Module Port for this Parameter. See Module.H for more on Module.
198  ////virtual void deletePort(ModuleParamPort const ptype);
199 
200  //! Set the topic of a Parameter Poster
201  /*! Will throw if the port is not found, eg, it has not been created
202  \note This method will post() the current Parameter value as soon as the topic is set */
203  ////virtual void setPosterTopicP(std::string const & topic);
204 
205  //! Set the topic filter of a Parameter Checker
206  /*! Will throw if the port is not found, eg, it has not been created */
207  ////virtual void setCheckerTopicFilterP(std::string const & topicfilt);
208 
209  //! Set the topic filter of a Parameter Subscriber
210  /*! Will throw if the port is not found, eg, it has not been created */
211  //// virtual void setSubscriberTopicFilterP(std::string const & topicfilt);
212 
213  //! Change the ParameterDef of this parameter
214  /*! Use with caution, only people who know what they are doing should use this function */
215  void changeParameterDef(ParameterDef<T> const & def);
216 
217  //! Set the parameter's callback
218  /*! The callback function is called each time one tries to change the value of the parameter. Try to avoid using
219  this so you won't confuse users of your class. In most cases, just use NRT_DECLARE_PARAMETER_WITH_CALLBACK.
220 
221  Default callback behavior is a no-op and the new value will be accepted. If overloading this function, check
222  for acceptable values and trigger any action, then just return if all went well. Otherwise, throw
223  nrt::exception::BadParameter to indicate that the proposed value is rejected.
224 
225  The callback should examine the candidate value newval and (1) if it does not like it, throw
226  nrt::exception::BadParameter, (2) otherwise, it is assumed that the value is accepted and the callback can
227  then allocate resources or do other work with that value. The Parameter is locked-up for writing as long as
228  the callback is running, to avoid destruction of the parameter and/or concurrent parameter value changes by
229  several different threads. Thus, callbacks should try to execute quickly, and should not call set(), etc on
230  the parameter as this will always deadlock (get() is allowed if your callback needs to know the current
231  value of the parameter). */
232  void setCallback(std::function<void(T const &)> cb);
233 
234  private:
235  std::function<void(T const &)> itsCallback; // optional callback function
236  T itsVal; // The actual value of the parameter
237  ParameterDef<T> const itsDef; // The parameter's definition
238 
239  ////std::shared_ptr<nrt::MessagePosterCore<nrt::ParameterPosting<T> > > itsPoster;
240  ////std::shared_ptr<nrt::MessageCheckerCore<nrt::ParameterChecking<T> > > itsChecker;
241  ////std::shared_ptr<nrt::ParameterMessageSubscriber<T> > itsSubscriber;
242  };
243 
244  // ######################################################################
245  //! A set of Parameters attached to a component
246  /*! This variadic template class is just for the convenience of adding several parameters to a Component in one
247  statement. */
248  template <class Param, class ... Tail>
249  class Parameter<Param, Tail ...> : public Param, public Parameter<Tail ...>
250  {
251  static_assert(std::is_base_of<nrt::ParameterBase, Param>::value,
252  "nrt::Parameter<...> template arguments must all be parameters (derive from nrt::ParameterBase");
253  };
254 
255  /*! @} */ // **********************************************************************
256 
257 
258 } // namespace nrt
259 
260 #endif // INCLUDE_NRT_CORE_MODEL_PARAMETER_H
261