Loading...
Searching...
No Matches
uhd::property< T > Class Template Referenceabstract

`#include <uhd/property_tree.hpp>`

Inheritance diagram for uhd::property< T >:
[legend]
Collaboration diagram for uhd::property< T >:
[legend]

## 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

  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:

- property_tree.hpp