From 54b8be72fd07bb51568ad5c4bad678b081a8dbe5 Mon Sep 17 00:00:00 2001
From: Josh Blum <josh@joshknows.com>
Date: Wed, 29 Jun 2011 11:26:33 -0700
Subject: uhd: properties tweaks and docs
---
host/include/uhd/property_tree.hpp | 37 +++++++++++++++++++++++++++----------
host/include/uhd/property_tree.ipp | 8 ++++----
host/lib/usrp/dboard_manager.cpp | 10 +++++-----
host/lib/usrp2/usrp2_impl.cpp | 8 ++++----
host/tests/property_test.cpp | 2 +-
5 files changed, 41 insertions(+), 24 deletions(-)
diff --git a/host/include/uhd/property_tree.hpp b/host/include/uhd/property_tree.hpp
index 63cd76a56..b20f3b779 100644
--- a/host/include/uhd/property_tree.hpp
+++ b/host/include/uhd/property_tree.hpp
@@ -35,15 +35,17 @@ template <typename T> class UHD_API property : boost::noncopyable{
public:
typedef boost::function<void(const T &)> subscriber_type;
typedef boost::function<T(void)> publisher_type;
- typedef boost::function<T(const T &)> master_type;
+ typedef boost::function<T(const T &)> coercer_type;
/*!
- * Register a master subscriber into the property.
- * A master is a special subscriber that coerces the value.
- * Only one master may be registered per property.
- * Registering a master replaces the previous master.
+ * Register a coercer into the property.
+ * A coercer is a special subscribes that coerces the value.
+ * Only one coercer may be registered per property.
+ * Registering a coercer replaces the previous coercer.
+ * \param coercer the coercer callback function
+ * \return a reference to this property for chaining
*/
- virtual property<T> &subscribe_master(const master_type &master) = 0;
+ virtual property<T> &coerce(const coercer_type &coercer) = 0;
/*!
* Register a publisher into the property.
@@ -51,6 +53,8 @@ public:
* Publishers are useful for creating read-only properties.
* Only one publisher may be registered per property.
* Registering a publisher replaces the previous publisher.
+ * \param publisher the publisher callback function
+ * \return a reference to this property for chaining
*/
virtual property<T> &publish(const publisher_type &publisher) = 0;
@@ -58,19 +62,32 @@ public:
* Register a subscriber into the property.
* All subscribers are called when the value changes.
* Once a subscriber is registered, it cannot be unregistered.
+ * \param subscriber the subscriber callback function
+ * \return a reference to this property for chaining
*/
virtual property<T> &subscribe(const subscriber_type &subscriber) = 0;
- //! Update calls all subscribers w/ the current value
+ /*!
+ * Update calls all subscribers w/ the current value.
+ * \return a reference to this property for chaining
+ */
virtual property<T> &update(void) = 0;
/*!
* Set the new value and call all subscribers.
- * The master is called first to coerce the value.
+ * The coercer (when provided) is called initially,
+ * and the coerced value is used to set the subscribers.
+ * \param value the new value to set on this property
+ * \return a reference to this property for chaining
*/
virtual property<T> &set(const T &value) = 0;
- //! Get the current value of this property
+ /*!
+ * Get the current value of this property.
+ * The publisher (when provided) yields the value,
+ * otherwise an internal shadow is used for the value.
+ * \return the current value in the property
+ */
virtual T get(void) const = 0;
};
@@ -100,7 +117,7 @@ public:
//! Get access to a property in the tree
template <typename T> property<T> &access(const path_type &path);
-protected:
+private:
//! Internal create property with wild-card type
virtual void _create(const path_type &path, const boost::shared_ptr<void> &prop) = 0;
diff --git a/host/include/uhd/property_tree.ipp b/host/include/uhd/property_tree.ipp
index 3dba6fb28..5fbb2dda5 100644
--- a/host/include/uhd/property_tree.ipp
+++ b/host/include/uhd/property_tree.ipp
@@ -29,8 +29,8 @@ namespace uhd{ namespace /*anon*/{
template <typename T> class UHD_API property_impl : public property<T>{
public:
- property<T> &subscribe_master(const typename property<T>::master_type &master){
- _master = master;
+ property<T> &coerce(const typename property<T>::coercer_type &coercer){
+ _coercer = coercer;
return *this;
}
@@ -50,7 +50,7 @@ public:
}
property<T> &set(const T &value){
- _value = boost::shared_ptr<T>(new T(_master.empty()? value : _master(value)));
+ _value = boost::shared_ptr<T>(new T(_coercer.empty()? value : _coercer(value)));
BOOST_FOREACH(typename property<T>::subscriber_type &subscriber, _subscribers){
subscriber(*_value); //let errors propagate
}
@@ -64,7 +64,7 @@ public:
private:
std::vector<typename property<T>::subscriber_type> _subscribers;
typename property<T>::publisher_type _publisher;
- typename property<T>::master_type _master;
+ typename property<T>::coercer_type _coercer;
boost::shared_ptr<T> _value;
};
diff --git a/host/lib/usrp/dboard_manager.cpp b/host/lib/usrp/dboard_manager.cpp
index b1c10e1c1..d5e7d5b8a 100644
--- a/host/lib/usrp/dboard_manager.cpp
+++ b/host/lib/usrp/dboard_manager.cpp
@@ -483,19 +483,19 @@ void dboard_manager::populate_prop_tree_from_subdev(
tree->create<int>(root / "gains"); //phony property so this dir exists
BOOST_FOREACH(const std::string &name, gain_names){
tree->create<double>(root / "gains" / name / "value")
- .subscribe_master(boost::bind(&get_set_gain, subdev, name, _1));
+ .coerce(boost::bind(&get_set_gain, subdev, name, _1));
tree->create<meta_range_t>(root / "gains" / name / "range")
.publish(boost::bind(&get_gain_range, subdev, name));
}
tree->create<double>(root / "freq/value")
- .subscribe_master(boost::bind(&get_set_freq, subdev, _1));
+ .coerce(boost::bind(&get_set_freq, subdev, _1));
tree->create<meta_range_t>(root / "freq/range")
.publish(boost::bind(&get_freq_range, subdev));
tree->create<std::string>(root / "antenna/value")
- .subscribe_master(boost::bind(&get_set_ant, subdev, _1));
+ .coerce(boost::bind(&get_set_ant, subdev, _1));
tree->create<std::vector<std::string> >(root / "antenna/options")
.publish(boost::bind(&get_ants, subdev));
@@ -504,11 +504,11 @@ void dboard_manager::populate_prop_tree_from_subdev(
.publish(boost::bind(&get_conn, subdev));
tree->create<bool>(root / "enabled")
- .subscribe_master(boost::bind(&get_set_enb, subdev, _1));
+ .coerce(boost::bind(&get_set_enb, subdev, _1));
tree->create<bool>(root / "use_lo_offset")
.publish(boost::bind(&get_use_lo_off, subdev));
tree->create<double>(root / "bandwidth/value")
- .subscribe_master(boost::bind(&get_set_bw, subdev, _1));
+ .coerce(boost::bind(&get_set_bw, subdev, _1));
}
diff --git a/host/lib/usrp2/usrp2_impl.cpp b/host/lib/usrp2/usrp2_impl.cpp
index e65461103..4c0eed7cc 100644
--- a/host/lib/usrp2/usrp2_impl.cpp
+++ b/host/lib/usrp2/usrp2_impl.cpp
@@ -433,10 +433,10 @@ usrp2_impl::usrp2_impl(const device_addr_t &_device_addr){
_mbc[mb].dsp_xports[dspno]->get_recv_buff(0.01).get(); //recv with timeout for expected
property_tree::path_type rx_dsp_path = mb_path / str(boost::format("rx_dsps/%u") % dspno);
_tree->create<double>(rx_dsp_path / "rate/value")
- .subscribe_master(boost::bind(&rx_dsp_core_200::set_host_rate, _mbc[mb].rx_dsps[dspno], _1))
+ .coerce(boost::bind(&rx_dsp_core_200::set_host_rate, _mbc[mb].rx_dsps[dspno], _1))
.subscribe(boost::bind(&usrp2_impl::update_rx_samp_rate, this, _1));
_tree->create<double>(rx_dsp_path / "freq/value")
- .subscribe_master(boost::bind(&rx_dsp_core_200::set_freq, _mbc[mb].rx_dsps[dspno], _1));
+ .coerce(boost::bind(&rx_dsp_core_200::set_freq, _mbc[mb].rx_dsps[dspno], _1));
_tree->create<meta_range_t>(rx_dsp_path / "freq/range")
.publish(boost::bind(&rx_dsp_core_200::get_freq_range, _mbc[mb].rx_dsps[dspno]));
_tree->create<stream_cmd_t>(rx_dsp_path / "stream_cmd")
@@ -452,10 +452,10 @@ usrp2_impl::usrp2_impl(const device_addr_t &_device_addr){
_tree->access<double>(mb_path / "tick_rate")
.subscribe(boost::bind(&tx_dsp_core_200::set_tick_rate, _mbc[mb].tx_dsp, _1));
_tree->create<double>(mb_path / "tx_dsps/0/rate/value")
- .subscribe_master(boost::bind(&tx_dsp_core_200::set_host_rate, _mbc[mb].tx_dsp, _1))
+ .coerce(boost::bind(&tx_dsp_core_200::set_host_rate, _mbc[mb].tx_dsp, _1))
.subscribe(boost::bind(&usrp2_impl::update_tx_samp_rate, this, _1));
_tree->create<double>(mb_path / "tx_dsps/0/freq/value")
- .subscribe_master(boost::bind(&usrp2_impl::set_tx_dsp_freq, this, mb, _1));
+ .coerce(boost::bind(&usrp2_impl::set_tx_dsp_freq, this, mb, _1));
_tree->create<meta_range_t>(mb_path / "tx_dsps/0/freq/range")
.publish(boost::bind(&usrp2_impl::get_tx_dsp_freq_range, this, mb));
diff --git a/host/tests/property_test.cpp b/host/tests/property_test.cpp
index cd9691dca..20f6b6924 100644
--- a/host/tests/property_test.cpp
+++ b/host/tests/property_test.cpp
@@ -113,7 +113,7 @@ BOOST_AUTO_TEST_CASE(test_prop_with_coercion){
prop.subscribe(boost::bind(&setter_type::doit, &setter, _1));
coercer_type coercer;
- prop.subscribe_master(boost::bind(&coercer_type::doit, &coercer, _1));
+ prop.coerce(boost::bind(&coercer_type::doit, &coercer, _1));
prop.set(42);
BOOST_CHECK_EQUAL(prop.get(), 40);
--
cgit v1.2.3