A class providing methods for the storage and lookup of control-parameter values. More...

#include <ControlParameterContainer.hpp>

Inheritance diagram for CDPL::Base::ControlParameterContainer:

Public Types
typedef ParameterMap::value_type	ParameterEntry
	A Base::LookupKey / Base::Any pair used to store the control-parameter values and associated keys. More...

typedef ParameterMap::const_iterator	ConstParameterIterator
	A constant iterator used to iterate over the control-parameter entries. More...

typedef std::function< void(const LookupKey &, const Any &)>	ParameterChangedCallbackFunction
	A functor class that wraps callback target functions which get invoked when the value of a control-parameter has changed. More...

typedef std::function< void(const LookupKey &)>	ParameterRemovedCallbackFunction
	A functor class that wraps callback target functions which get invoked when a control-parameter entry has been removed. More...

typedef std::function< void()>	ParentChangedCallbackFunction
	A functor class that wraps callback target functions which get invoked when the parent container has been changed or was detached. More...

Public Member Functions
std::size_t	getNumParameters () const
	Returns the number of container entries. More...

template<typename T >
void	setParameter (const LookupKey &key, T &&val)
	Sets the value of the control-parameter specified by key to val. More...

const Any &	getParameter (const LookupKey &key, bool throw_=false, bool local=false) const
	Returns the value of the control-parameter specified by key. More...

template<typename T >
const T &	getParameter (const LookupKey &key, bool local=false) const
	Returns the value of the control-parameter specified by key as a `const` reference to an object of type T. More...

template<typename T >
const T &	getParameterOrDefault (const LookupKey &key, const T &def_val, bool local=false) const
	Returns the value of the control-parameter specified by key as a `const` reference to an object of type T, or the default value def_val if a stored value does not exist. More...

bool	removeParameter (const LookupKey &key)
	Removes the entry for the control-parameter specified by key. More...

void	clearParameters ()
	Erases all container entries. More...

bool	isParameterSet (const LookupKey &key, bool local=false) const
	Tells whether or not a value has been assigned to the control-parameter specified by key. More...

void	addParameters (const ControlParameterContainer &cntnr)
	Adds the control-parameter value entries in the `ControlParameterContainer` instance cntnr. More...

void	copyParameters (const ControlParameterContainer &cntnr)
	Replaces the current set of properties by a copy of the entries in cntnr. More...

ConstParameterIterator	getParametersBegin () const
	Returns a constant iterator pointing to the beginning of the entries. More...

ConstParameterIterator	getParametersEnd () const
	Returns a constant iterator pointing to the end of the entries. More...

ConstParameterIterator	begin () const
	Returns a constant iterator pointing to the beginning of the entries. More...

ConstParameterIterator	end () const
	Returns a constant iterator pointing to the end of the entries. More...

void	setParent (const ControlParameterContainer *cntnr)
	Sets or removes the parent control-parameter container used to resolve requests for missing entries. More...

const ControlParameterContainer *	getParent () const
	Returns a pointer to the parent control-parameter container. More...

std::size_t	registerParameterChangedCallback (const ParameterChangedCallbackFunction &func)
	Registers a callback target function that gets invoked when the value of a control-parameter has changed. More...

void	unregisterParameterChangedCallback (std::size_t id)
	Unregisters the callback specified by id. More...

std::size_t	registerParameterRemovedCallback (const ParameterRemovedCallbackFunction &func)
	Registers a callback target function that gets invoked when a control-parameter entry has been removed. More...

void	unregisterParameterRemovedCallback (std::size_t id)
	Unregisters the callback specified by id. More...

std::size_t	registerParentChangedCallback (const ParentChangedCallbackFunction &func)
	Registers a callback target function that gets invoked when the parent container has been changed or was detached. More...

void	unregisterParentChangedCallback (std::size_t id)
	Unregisters the callback specified by id. More...

const ControlParameterContainer &	getParameters () const
	Returns a `const` reference to itself. More...

Protected Member Functions
	ControlParameterContainer ()
	Constructs an empty `ControlParameterContainer` instance. More...

	ControlParameterContainer (const ControlParameterContainer &cntnr)
	Constructs a copy of the `ControlParameterContainer` instance cntnr. More...

virtual	~ControlParameterContainer ()
	Destructor. More...

ControlParameterContainer &	operator= (const ControlParameterContainer &cntnr)
	Assignment operator. More...

Detailed Description

A class providing methods for the storage and lookup of control-parameter values.

The purpose of ControlParameterContainer is to provide a common facility for the storage and lookup of dynamic parameter values to subclasses which can be used to control their runtime-behaviour.

For the explicit assignment of control-parameter values the method setParameter() is provided which expects the key of the control-parameter as its first and the value to assign as the second argument. The availability of a value for a particular control-parameter can be tested by the method isParameterSet(). For the retrieval of control-parameter values the getParameter() family of overloaded methods is provided which expect the key of the control-parameter as an argument. The method getParameterOrDefault() additionally allows to specify a default value that gets returned if an entry for the requested control-parameter value does not exist. ControlParameterContainer guarantees that the complexity of these operations is never worse than logarithmic.

Control-parameter values are stored in an associative map as Base::LookupKey / Base::Any pairs of type ControlParameterContainer::ParameterEntry. The current number of entries can be queried with the method getNumParameters(). Iterators pointing to the beginning and end of the container are obtained via the methods getEntriesBegin() and getEntriesEnd(), respectively.

ControlParameterContainer allows for an arrangement of instances in a tree-like hierarchy where each non-root instance has exactly one parent and zero or more children. In such hierarchies, a child container forwards requests for control-parameter values to their parents if they do not contain a local entry for a given control-parameter. The parent container is set and detached by the method setParent(). A ControlParameterContainer instance automatically keeps track of any links from and to other instances in the hierarchy and detaches any parent or child containers on object destruction.

For the notification of client code about any changes that affect control-parameter values, the ControlParameterContainer interface provides three methods for the registration of callback functions:

registerParameterChangedCallback()
registers callback target functions that get invoked when the value of a control-parameter has changed
registerParameterRemovedCallback()
registers callback target functions that get invoked when a control-parameter entry has been removed
and registerParentChangedCallback()
is used to register callback target functions that get invoked when the parent container has been changed or was detached

Each of these methods returns a numeric identifier for the registered callback function. For callback unregistration purposes the methods unregisterParameterChangedCallback(), unregisterParameterRemovedCallback() and unregisterParentChangedCallback() are provided. These methods require the previously obtained numeric identifier of the callback to be passed as an argument.

Member Typedef Documentation

◆ ParameterEntry

typedef ParameterMap::value_type CDPL::Base::ControlParameterContainer::ParameterEntry

A Base::LookupKey / Base::Any pair used to store the control-parameter values and associated keys.

◆ ConstParameterIterator

typedef ParameterMap::const_iterator CDPL::Base::ControlParameterContainer::ConstParameterIterator

A constant iterator used to iterate over the control-parameter entries.

◆ ParameterChangedCallbackFunction

typedef std::function<void(const LookupKey&, const Any&)> CDPL::Base::ControlParameterContainer::ParameterChangedCallbackFunction

A functor class that wraps callback target functions which get invoked when the value of a control-parameter has changed.

ParameterChangedCallbackFunction allows to wrap any function pointer or function object compatible with a return type of void and two arguments of type const Base::LookupKey& and Base::Any (see [FUNWRP]).

◆ ParameterRemovedCallbackFunction

typedef std::function<void(const LookupKey&)> CDPL::Base::ControlParameterContainer::ParameterRemovedCallbackFunction

A functor class that wraps callback target functions which get invoked when a control-parameter entry has been removed.

ParameterRemovedCallbackFunction allows to wrap any function pointer or function object compatible with a return type of void and an argument of type const Base::LookupKey& (see [FUNWRP]).

◆ ParentChangedCallbackFunction

typedef std::function<void()> CDPL::Base::ControlParameterContainer::ParentChangedCallbackFunction

A functor class that wraps callback target functions which get invoked when the parent container has been changed or was detached.

ParentChangedCallbackFunction allows to wrap any function pointer or function object compatible with a return type of void and no arguments (see [FUNWRP]).

See also: setParent()

Constructor & Destructor Documentation

◆ ControlParameterContainer() [1/2]

CDPL::Base::ControlParameterContainer::ControlParameterContainer ( )

inlineprotected

Constructs an empty ControlParameterContainer instance.

◆ ControlParameterContainer() [2/2]

CDPL::Base::ControlParameterContainer::ControlParameterContainer ( const ControlParameterContainer & cntnr )

inlineprotected

Constructs a copy of the ControlParameterContainer instance cntnr.

Parameters

cntnr The ControlParameterContainer instance to copy.

Note: Only the control-parameter entries of cntnr are copied. Entries in the parent container of cntnr (if set) will be ignored (see setParent()).

◆ ~ControlParameterContainer()

virtual CDPL::Base::ControlParameterContainer::~ControlParameterContainer ( )

protectedvirtual

Destructor.

The parent pointer of any children will be set to null before the instance gets destroyed (see setParent()).

Member Function Documentation

◆ getNumParameters()

std::size_t CDPL::Base::ControlParameterContainer::getNumParameters ( ) const

Returns the number of container entries.

Returns: The number of container entries.

◆ setParameter()

template<typename T >

void CDPL::Base::ControlParameterContainer::setParameter	(	const LookupKey &	key,
		T &&	val
	)

Sets the value of the control-parameter specified by key to val.

If val is of type Base::Any and empty, i.e. the method Base::Any::isEmpty() returns true, and a control-parameter entry for key exists, the entry gets erased (equivalent to removeParameter() with key as argument). Otherwise the control-parameter is assigned the specified value and any callback functions registered by registerParameterChangedCallback() will be invoked with key and val provided as arguments. Callbacks of affected direct and indirect children which do not have an entry for the specified control-parameter also get invoked.

Parameters

key	The key of the control-parameter value to assign or remove.
val	The value of the control-parameter.

◆ getParameter() [1/2]

const Any& CDPL::Base::ControlParameterContainer::getParameter	(	const LookupKey &	key,
		bool	throw_ = `false`,
		bool	local = `false`
	)		const

Returns the value of the control-parameter specified by key.

If the container contains an entry for the specified control-parameter, the stored value will be returned. If an entry for the control-parameter does not exist, the results depends on the arguments throw_ and local:

If a parent container has been set and the argument local is false, the request is forwarded to the parent (which may also forward the request). Otherwise an empty Base::Any object is returned if _throw is false, and a Base::ItemNotFound exception will be thrown if _throw is true.

Parameters

key	The key of the control-parameter value to return.
throw_	Specifies whether or not to throw a Base::ItemNotFound exception if an entry for the control-parameter does not exist.
local	Specifies whether or not the request shall be forwarded to the parent container if a local entry for the control-parameter does not exist.

Returns: The stored control-parameter value or an empty Base::Any object.

Exceptions

Base::ItemNotFound if an entry for the requested control-parameter value does not exist and _throw is true.

◆ getParameter() [2/2]

template<typename T >

const T & CDPL::Base::ControlParameterContainer::getParameter	(	const LookupKey &	key,
		bool	local = `false`
	)		const

Returns the value of the control-parameter specified by key as a const reference to an object of type T.

If the container contains an entry for the specified control-parameter, the stored value will be returned. If an entry for the control-parameter does not exist, a parent container has been set and the argument local is false, the call is forwarded to the parent (which may also forward the request). Otherwise a Base::ItemNotFound exception will be thrown.

Parameters

key	The key of the control-parameter value to return.
local	Specifies whether or not the request shall be forwarded to the parent container if a local entry for the control-parameter does not exist.

Returns: The stored control-parameter value as a const reference to an object of type T.

Exceptions

Base::ItemNotFound if an entry for the requested control-parameter value does not exist, and Base::BadCast if the stored control-parameter value cannot be casted to the target type T.

◆ getParameterOrDefault()

template<typename T >

const T & CDPL::Base::ControlParameterContainer::getParameterOrDefault	(	const LookupKey &	key,
		const T &	def_val,
		bool	local = `false`
	)		const

Returns the value of the control-parameter specified by key as a const reference to an object of type T, or the default value def_val if a stored value does not exist.

If the container contains an entry for the specified control-parameter, the stored value will be returned. If an entry for the control-parameter does not exist, a parent container has been set and the argument local is false, the call is forwarded to the parent (which may also forward the request). Otherwise the default value specified by def_val is returned.

Parameters

key	The key of the control-parameter for which to return the stored (or specified default) value.
def_val	The default value that shall be returned if an entry for the specified control-parameter does not exist.
local	Specifies whether or not the request shall be forwarded to the parent container if a local entry for the control-parameter does not exist.

Returns: The stored control-parameter value or the default specified by def_val.

Exceptions

Base::BadCast if the stored control-parameter value cannot be casted to the target type T.

◆ removeParameter()

bool CDPL::Base::ControlParameterContainer::removeParameter ( const LookupKey & key )

Removes the entry for the control-parameter specified by key.

If an entry for the control-parameter specified by key exists, the entry is removed and any callback functions registered by registerParameterRemovedCallback() will be invoked with key provided as an argument. Callbacks of affected direct and indirect children which do not have an entry for the specified control-parameter also get invoked.

Parameters

key	The key of the control-parameter entry to remove.

Returns: true if an entry for key could be found and was removed, and false otherwise.

◆ clearParameters()

void CDPL::Base::ControlParameterContainer::clearParameters ( )

Erases all container entries.

For each container entry, any callback functions registered by registerParameterRemovedCallback() will be invoked with the key of the removed control-parameter entry as an argument. Callbacks of affected direct and indirect children which do not have an entry for the erased control-parameter also get invoked.

◆ isParameterSet()

bool CDPL::Base::ControlParameterContainer::isParameterSet	(	const LookupKey &	key,
		bool	local = `false`
	)		const

Tells whether or not a value has been assigned to the control-parameter specified by key.

If the container does not contain an entry for the specified control-parameter, a parent container has been set and the argument local is false, the call is forwarded to the parent (which may also forward the call). Otherwise the result of the local search is returned.

Parameters

key	The key of the control-parameter.
local	Specifies whether or not the query shall be forwarded to the parent container if a local entry for the control-parameter does not exist.

Returns: true if an entry for the specified control-parameter could be found, and false otherwise.

◆ addParameters()

void CDPL::Base::ControlParameterContainer::addParameters ( const ControlParameterContainer & cntnr )

Adds the control-parameter value entries in the ControlParameterContainer instance cntnr.

Any control-parameter values which have no corresponding assigned value in cntnr are left unchanged. Otherwise the value of the local control-parameter gets overwritten by the value stored in cntnr and any callback functions registered by registerParameterChangedCallback() will be invoked with key and value provided as arguments. Callbacks of affected direct and indirect children which do not have an entry for the specified control-parameter also get invoked.

Parameters

cntnr The ControlParameterContainer instance containing the control-parameter value entries to add.

◆ copyParameters()

void CDPL::Base::ControlParameterContainer::copyParameters ( const ControlParameterContainer & cntnr )

Replaces the current set of properties by a copy of the entries in cntnr.

The assignment is equivalent to first erasing all entries by calling clearParameters() and then calling setParameter() for each key/value entry in cntnr.

Parameters

cntnr The ControlParameterContainer instance containing the control-parameter value entries to add.

◆ getParametersBegin()

ConstParameterIterator CDPL::Base::ControlParameterContainer::getParametersBegin ( ) const

Returns a constant iterator pointing to the beginning of the entries.

Returns: A constant iterator pointing to the beginning of the entries.

◆ getParametersEnd()

ConstParameterIterator CDPL::Base::ControlParameterContainer::getParametersEnd ( ) const

Returns a constant iterator pointing to the end of the entries.

Returns: A constant iterator pointing to the end of the entries.

◆ begin()

ConstParameterIterator CDPL::Base::ControlParameterContainer::begin ( ) const

Returns a constant iterator pointing to the beginning of the entries.

Returns: A constant iterator pointing to the beginning of the entries.

◆ end()

ConstParameterIterator CDPL::Base::ControlParameterContainer::end ( ) const

Returns a constant iterator pointing to the end of the entries.

Returns: A constant iterator pointing to the end of the entries.

◆ setParent()

void CDPL::Base::ControlParameterContainer::setParent ( const ControlParameterContainer * cntnr )

Sets or removes the parent control-parameter container used to resolve requests for missing entries.

A control-parameter container that has been set as a parent gets used whenever a request for a control-parameter value cannot be satisfied locally by the container itself. That is, if a key/value entry for a given control-parameter does not exist, the request is simply forwarded to the parent container (which may also forward the request).

Any callback functions registered by registerParentChangedCallback() will be invoked after the new parent container has been set (or the old container was detached by providing a null pointer). Callbacks of any direct and indirect children also get invoked.

Parameters

cntnr A pointer to the parent control-parameter container or null. If the pointer is null, the currently set parent container (if any) gets detached.

◆ getParent()

const ControlParameterContainer* CDPL::Base::ControlParameterContainer::getParent ( ) const

Returns a pointer to the parent control-parameter container.

Returns: A pointer to the parent control-parameter container, or null if no parent container has been set.

See also: setParent()

◆ registerParameterChangedCallback()

std::size_t CDPL::Base::ControlParameterContainer::registerParameterChangedCallback ( const ParameterChangedCallbackFunction & func )

Registers a callback target function that gets invoked when the value of a control-parameter has changed.

Parameters

func	A ControlParameterContainer::ParameterChangedCallbackFunction object wrapping the target function.

Returns: An identifier for the registered callback.

◆ unregisterParameterChangedCallback()

void CDPL::Base::ControlParameterContainer::unregisterParameterChangedCallback ( std::size_t id )

Unregisters the callback specified by id.

If a registered callback with the identifier id does not exist, the method has no effect.

Parameters

id	The identifier of the callback to unregister.

◆ registerParameterRemovedCallback()

std::size_t CDPL::Base::ControlParameterContainer::registerParameterRemovedCallback ( const ParameterRemovedCallbackFunction & func )

Registers a callback target function that gets invoked when a control-parameter entry has been removed.

Parameters

func	A ControlParameterContainer::ParameterRemovedCallbackFunction object wrapping the target function.

Returns: An identifier for the registered callback.

◆ unregisterParameterRemovedCallback()

void CDPL::Base::ControlParameterContainer::unregisterParameterRemovedCallback ( std::size_t id )

Unregisters the callback specified by id.

If a registered callback with the identifier id does not exist, the method has no effect.

Parameters

id	The identifier of the callback to unregister.

◆ registerParentChangedCallback()

std::size_t CDPL::Base::ControlParameterContainer::registerParentChangedCallback ( const ParentChangedCallbackFunction & func )

Registers a callback target function that gets invoked when the parent container has been changed or was detached.

Parameters

func	A ControlParameterContainer::ParentChangedCallbackFunction object wrapping the target function.

Returns: An identifier for the registered callback.

◆ unregisterParentChangedCallback()

void CDPL::Base::ControlParameterContainer::unregisterParentChangedCallback ( std::size_t id )

Unregisters the callback specified by id.

If a registered callback with the identifier id does not exist, the method has no effect.

Parameters

id	The identifier of the callback to unregister.

◆ getParameters()

const CDPL::Base::ControlParameterContainer & CDPL::Base::ControlParameterContainer::getParameters ( ) const

inline

Returns a const reference to itself.

Returns: A const reference to itself.

◆ operator=()

ControlParameterContainer& CDPL::Base::ControlParameterContainer::operator= ( const ControlParameterContainer & cntnr )

protected

Assignment operator.

Internally calls copyParameters() to perform the actual work.

Parameters

cntnr The ControlParameterContainer instance to copy.

Returns: A reference to itself.

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

ControlParameterContainer.hpp

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ ParameterEntry

◆ ConstParameterIterator

◆ ParameterChangedCallbackFunction

◆ ParameterRemovedCallbackFunction

◆ ParentChangedCallbackFunction

Constructor & Destructor Documentation

◆ ControlParameterContainer() [1/2]

◆ ControlParameterContainer() [2/2]

◆ ~ControlParameterContainer()

Member Function Documentation

◆ getNumParameters()

◆ setParameter()

◆ getParameter() [1/2]

◆ getParameter() [2/2]

◆ getParameterOrDefault()

◆ removeParameter()

◆ clearParameters()

◆ isParameterSet()

◆ addParameters()

◆ copyParameters()

◆ getParametersBegin()

◆ getParametersEnd()

◆ begin()

◆ end()

◆ setParent()

◆ getParent()

◆ registerParameterChangedCallback()

◆ unregisterParameterChangedCallback()

◆ registerParameterRemovedCallback()

◆ unregisterParameterRemovedCallback()

◆ registerParentChangedCallback()

◆ unregisterParentChangedCallback()

◆ getParameters()

◆ operator=()