uhd: properties tweaks and docs

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);