#include <Parameter.H>

template<class T>
class nrt::Parameter< T >

A changeable parameter for a Component.

Parameters are used to expose user configurable settings for a Component. They can be specified from the command line and will be set by the time Component::preStart() has been called on the Component which owns the Parameter.

In general, Parameters should be member variables of classes which inherit from Component (including those that inherit from Module). The Parameter's constructor should then be called in the Component's initialization list, and should be passed a pointer to the proper ParameterDef definition as well as a pointer to the Component via the "this" keyword. E.g.

      nrt::ParameterCategory CoolParamCateg("Cool Parameter Related Options");
      nrt::ParameterDef<double> CoolParamDef("coolparam", "Some Cool Parameter", 2.0,
                                            {1.0, 2.0, 3.0, 4.0},  CoolParamCateg);

      class MyClass : public nrt::Component
      {
      public:
        MyClass(std::string instanceID) : nrt::Component(instanceID), itsCoolParam(CoolParamDef, this)
        { }
      private:
        nrt::Parameter<double> itsCoolParam;
      };

Parameters also have an optional callback member which will be called whenever the Parameter's value is changed.

See examples in test-Component.C and test-Option.C

Examples:: tests/test-Module.C.

Definition at line 181 of file Parameter.H.

Inheritance diagram for nrt::Parameter< T >:

List of all members.

Public Member Functions
	Parameter (ParameterDef< T > const &def, Component *owner, std::function< void(T const &)> callback=std::function< void(T const &)>())
	Constructor.
template<class Comp >
	Parameter (ParameterDef< T > const &def, Comp owner, void(Comp::callback)(T const &))
	Simpler constructor with a callback that is a member function of Component (or derivative)
template<class Comp >
	Parameter (ParameterDef< T > const &def, Comp *owner, OnlineChangePolicy policy)
	Construct a Parameter with no callback, explicitely disallowing online changes.
virtual	~Parameter ()
	Destructor.
virtual std::string const	name () const
	Get the parameter name. If you need more info about this parameter, try summary()
T	getVal () const
	Get the value of this Parameter.
void	setVal (T const &newVal)
	Set the value of this Parameter.
virtual void	setValString (std::string const &valstring)
	Set the value from a string representation of it.
virtual std::string const	getValString () const
	Get the value as a string representation of it.
void	setCallback (std::function< void(T const &newVal)> callback)
	Set the callback of this Parameter with an std::function callback.
template<class Comp >
void	setCallback (void(Comp::*callback)(T const &))
	Set the callback of this Parameter with a Component member function callback.
bool	isDefault () const
	Has this Parameter been set externally, or is it just the default value?
virtual ParameterSummary const	summary (ParameterState const state) const
	Get summary info about this parameter.
virtual void	createPort (ModuleParamPort const ptype, std::string const &module, std::string const &descriptor)
	Create a Module Port for this Parameter. See Module.H for more on Module.
virtual void	deletePort (ModuleParamPort const ptype)
	Delete a Module Port for this Parameter. See Module.H for more on Module.
virtual void	setPosterTopic (std::string const &topic)
	Set the topic of a Parameter Poster.
virtual void	setCheckerTopicFilter (std::string const &topicfilt)
	Set the topic filter of a Parameter Checker.
virtual void	setSubscriberTopicFilter (std::string const &topicfilt)
	Set the topic filter of a Parameter Subscriber.
template<class T>
void	setCallback (std::function< void(T const &)> callback)

Constructor & Destructor Documentation

template<class T>

Parameter::Parameter	(	nrt::ParameterDef< T > const &	def,
		nrt::Component *	owner,
		std::function< void(T const &)>	callback = `std::function<void(T const &)>()`
	)		`[inline]`

Constructor.

Parameters:

def	A pointer to the definition for this parameter (given by a ParameterDef).
owner	A pointer to the Component which contains this parameter as a member variable. Beware that it must be guaranteed that the owner always outlives the Parameter, as the Parameter registers/unregisters with the owner in the Parameter constructor/destructor. Thus, it is highly recommended that Parameter objects only be instantiated as member variables of Component objects.
callback	A std::function that will be called whenever the value of this Parameter is modified. This function should return true if passed candidate new parameter value is accepted, and false if not.

With this constructor, you would specify a callback as follows:

          void myfreefunction(myType const & val) { }

          nrt::Parameter<myType> p(def, owner, &myfreefunction)

If you callback function is a member function of the component owning the parameter, see the second Parameter constructor.

Definition at line 43 of file ParameterImpl.H.

References nrt::Component::addParameter(), and nrt::ParameterDef< T >::defaultValue().

template<class T>

template<class Comp >

Parameter::Parameter	(	nrt::ParameterDef< T > const &	def,
		Comp *	owner,
		void(Comp::*)(T const &)	callback
	)		`[inline, explicit]`

Simpler constructor with a callback that is a member function of Component (or derivative)

With this constructor, you would specify a callback as follows:

          class MyComponent : public nrt::Component {
            public:
              nrt::Parameter<myType> param;
              void mycallback(myType const & val) { }
          };

          // constructor:
          MyComponent::MyComponent() : nrt::Component(), param(def, this, &MyComponent::mycallback)
          { }

Definition at line 57 of file ParameterImpl.H.

References nrt::ParameterDef< T >::defaultValue().

template<class T>

template<class Comp >

Parameter::Parameter	(	nrt::ParameterDef< T > const &	def,
		Comp *	owner,
		nrt::OnlineChangePolicy	policy
	)		`[inline]`

Construct a Parameter with no callback, explicitely disallowing online changes.

Parameters created with this constructor will throw a ParameterException if setVal() is called after its owner has been started().

Definition at line 72 of file ParameterImpl.H.

Member Function Documentation

template<class T>

void Parameter::setVal ( T const & newVal ) [inline]

Set the value of this Parameter.

Will throw nrt::exception::ParameterException if the new value is not accepted, in which case the old value will remain in the Parameter.

Definition at line 117 of file ParameterImpl.H.

References nrt::exception::Exception::what().

Referenced by nrt::Component::setParamVal().

template<class T >

void Parameter::setValString ( std::string const & valstring ) [inline, virtual]

Set the value from a string representation of it.

Exceptions:

nrt::exception::ParameterException if the given string cannot be converted (using boost::lexical_cast) to a valid Parameter value.

Implements nrt::ParameterBase.

Definition at line 179 of file ParameterImpl.H.

template<class T>

void nrt::Parameter< T >::setCallback ( std::function< void(T const &newVal)> callback )

Set the callback of this Parameter with an std::function callback.

The callback should examine the candidate value newVal and (1) if it does not like it, throw nrt::exception::BadParameter, (2) otherwise, it is assumed that the value is accepted and the callback can then allocate resources or do other work with that value. The Parameter is locked-up for writing as long as the callback is running, to avoid destruction of the parameter and/or concurrent parameter value changes by several different threads. Thus, callbacks should try to execute quickly, and should not call setVal(), etc on the parameter as this will always deadlock (getVal() is allowed if your callback needs to know the current value of the parameter).

template<class T >

void Parameter::createPort	(	ModuleParamPort const	ptype,
		std::string const &	module,
		std::string const &	descriptor
	)		`[inline, virtual]`

Create a Module Port for this Parameter. See Module.H for more on Module.

Note:: This method will post() the current Parameter value as soon as the port is created

Implements nrt::ParameterBase.

Definition at line 234 of file ParameterImpl.H.

References nrt::Checker, nrt::Poster, and nrt::Subscriber.

template<class T >

void Parameter::setPosterTopic ( std::string const & topic ) [inline, virtual]

Set the topic of a Parameter Poster.

Will throw if the port is not found, eg, it has not been created

Note:: This method will post() the current Parameter value as soon as the topic is set

Implements nrt::ParameterBase.

Definition at line 277 of file ParameterImpl.H.

template<class T >

void Parameter::setCheckerTopicFilter ( std::string const & topicfilt ) [inline, virtual]

Set the topic filter of a Parameter Checker.

Will throw if the port is not found, eg, it has not been created

Implements nrt::ParameterBase.

Definition at line 286 of file ParameterImpl.H.

template<class T >

void Parameter::setSubscriberTopicFilter ( std::string const & topicfilt ) [inline, virtual]

Set the topic filter of a Parameter Subscriber.

Will throw if the port is not found, eg, it has not been created

Implements nrt::ParameterBase.

Definition at line 295 of file ParameterImpl.H.

The documentation for this class was generated from the following files:

include/nrt/Core/Model/Parameter.H
include/nrt/Core/Model/details/ParameterImpl.H

template<class T> class nrt::Parameter< T >

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation

template<class T>
class nrt::Parameter< T >