uhd::property< T > Class Template Reference

#include <uhd/property_tree.hpp>

Inheritance diagram for uhd::property< T >:

Public Types
typedef std::function< void(const T &)>	subscriber_type
typedef std::function< T(void)>	publisher_type
typedef std::function< T(const T &)>	coercer_type

Public Member Functions
virtual	~property (void)=0
virtual property< T > &	set_coercer (const coercer_type &coercer)=0
virtual property< T > &	set_publisher (const publisher_type &publisher)=0
virtual property< T > &	add_desired_subscriber (const subscriber_type &subscriber)=0
virtual property< T > &	add_coerced_subscriber (const subscriber_type &subscriber)=0
virtual property< T > &	update (void)=0
virtual property< T > &	set (const T &value)=0
virtual property< T > &	set_coerced (const T &value)=0
virtual const T	get (void) const =0
virtual const T	get_desired (void) const =0
virtual bool	empty (void) const =0

Detailed Description

template<typename T>
class uhd::property< T >

A templated property interface for holding the state associated with a property in a uhd::property_tree and registering callbacks when that value changes.

A property is defined to have two separate values:

• Desired value: Value requested by the user
• Coerced value: Value that was actually possible given HW and other requirements

By default, the desired and coerced values are identical as long as the property is not coerced. A property can be coerced in two ways:

1. Using a coercer: A callback function that takes in a desired value and produces a coerced value. A property must have exactly one coercer.
2. Manual coercion: Manually calling the set_coerced API function to coerce the value of the property. In order to use manual coercion, the property must be created with the MANUAL_COERCE mode. If the coerce mode for a property is AUTO_COERCE then it always has a coercer. If the set_coercer API is never used, then the default coercer is used which simply set the coerced value to the desired value.

It is possible to get notified every time the desired or coerced values of a property potentially change using subscriber callbacks. Every property can have zero or more desired and coerced subscribers.

If storing the property readback state in software is not appropriate (for example if it needs to be queried from hardware) then it is possible to use a publisher callback to get the value of the property. Calling get on the property will always call the publisher and the cached desired and coerced values are updated only using set* calls. A property must have at most one publisher. It is legal to have both a coercer and publisher for a property but the only way to access the desired and coerced values in that case would be by notification using the desired and coerced subscribers. Publishers are useful for creating read-only properties.

Requirements for the template type T:

• T must have a copy constructor
• T must have an assignment operator

Member Typedef Documentation

coercer_type

template<typename T >

typedef std::function<T(const T&)> uhd::property< T >::coercer_type

publisher_type

template<typename T >

typedef std::function<T(void)> uhd::property< T >::publisher_type

subscriber_type

template<typename T >

typedef std::function<void(const T&)> uhd::property< T >::subscriber_type

Constructor & Destructor Documentation

~property()

template<typename T >

uhd::property< T >::~property ( void  )

pure virtual

Member Function Documentation

add_coerced_subscriber()

template<typename T >

virtual property< T > & uhd::property< T >::add_coerced_subscriber ( const subscriber_type &  subscriber )

pure virtual

Register a subscriber into the property. All coerced subscribers are called when the coerced value potentially changes.

Once a subscriber is registered, it cannot be unregistered.

Parameters

subscriber

the subscriber callback function

Returns

a reference to this property for chaining

add_desired_subscriber()

template<typename T >

virtual property< T > & uhd::property< T >::add_desired_subscriber ( const subscriber_type &  subscriber )

pure virtual

Register a subscriber into the property. All desired subscribers are called when the desired value potentially changes.

Once a subscriber is registered, it cannot be unregistered.

Parameters

subscriber

the subscriber callback function

Returns

a reference to this property for chaining

empty()

template<typename T >

virtual bool uhd::property< T >::empty ( void  ) const

pure virtual

A property is empty if it has never been set. A property with a publisher is never empty.

Returns

true if the property is empty

get()

template<typename T >

virtual const T uhd::property< T >::get ( void  ) const

pure virtual

Get the current value of this property. The publisher (when provided) yields the value, otherwise an internal coerced value is returned.

Returns

the current value in the property

Exceptions

uhd::assertion_error

get_desired()

template<typename T >

virtual const T uhd::property< T >::get_desired ( void  ) const

pure virtual

Get the current desired value of this property.

Returns

the current desired value in the property

Exceptions

uhd::assertion_error

set()

template<typename T >

virtual property< T > & uhd::property< T >::set ( const T &  value )

pure virtual

Set the new value and call all the necessary subscribers. Order of operations:

• The desired value of the property is updated
• All desired subscribers are called
• If coerce mode is AUTO then the coercer is called
• If coerce mode is AUTO then all coerced subscribers are called

Parameters

value

the new value to set on this property

Returns

a reference to this property for chaining

Exceptions

uhd::assertion_error

set_coerced()

template<typename T >

virtual property< T > & uhd::property< T >::set_coerced ( const T &  value )

pure virtual

Set a coerced value and call all subscribers. The coercer is bypassed, and the specified value is used as the coerced value. All coerced subscribers are called. This function can only be used when the coerce mode is set to MANUAL_COERCE.

Parameters

value

the new value to set on this property

Returns

a reference to this property for chaining

Exceptions

uhd::assertion_error

set_coercer()

template<typename T >

virtual property< T > & uhd::property< T >::set_coercer ( const coercer_type &  coercer )

pure virtual

Register a coercer into the property. A coercer is a callback function that updates the coerced value of a property.

Only one coercer may be registered per property.

Parameters

coercer

the coercer callback function

Returns

a reference to this property for chaining

Exceptions

uhd::assertion_error

if called more than once

set_publisher()

template<typename T >

virtual property< T > & uhd::property< T >::set_publisher ( const publisher_type &  publisher )

pure virtual

Register a publisher into the property. A publisher is a callback function the provides the value for a property.

Only one publisher may be registered per property.

Parameters

publisher

the publisher callback function

Returns

a reference to this property for chaining

Exceptions

uhd::assertion_error

if called more than once

update()

template<typename T >

virtual property< T > & uhd::property< T >::update ( void  )

pure virtual

Calls all subscribers with the current value.

Returns

a reference to this property for chaining

Exceptions

uhd::assertion_error

---

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

• include/uhd/property_tree.hpp