USRP Hardware Driver and USRP Manual Version: 4.2.0.0
UHD and USRP Manual
uhd::property< T > Class Template Referenceabstract

#include <uhd/property_tree.hpp>

Inheritance diagram for uhd::property< T >:
uhd::property_iface

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
 
- Public Member Functions inherited from uhd::property_iface
virtual ~property_iface ()=default
 

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
subscriberthe 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
subscriberthe 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
valuethe 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
valuethe 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
coercerthe coercer callback function
Returns
a reference to this property for chaining
Exceptions
uhd::assertion_errorif 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
publisherthe publisher callback function
Returns
a reference to this property for chaining
Exceptions
uhd::assertion_errorif 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: