[Commit-gnuradio] [gnuradio] 03/57: controlport: adding a 'toggle' interface for ControlPort.

[git]

This is an automated email from the git hooks/post-receive script.

trondeau pushed a commit to branch master
in repository gnuradio.

commit 792f54c5d8a69ace970cdeb8793b6432f23673f1
Author: Tom Rondeau <address@hidden>
Date:   Tue Apr 15 18:20:29 2014 -0400

    controlport: adding a 'toggle' interface for ControlPort.
    
    This is very similar and accessed like a 'set' function only it does not 
take a parameter; it simply calls a function. Meant to toggle an action, like 
reseting the performance counters or locking/unlocking the flowgraph.
---
 .../include/gnuradio/rpccallbackregister_base.h    |  16 +-
 .../include/gnuradio/rpcregisterhelpers.h          | 756 ++++++++++++++++++---
 2 files changed, 673 insertions(+), 99 deletions(-)

diff --git a/gnuradio-runtime/include/gnuradio/rpccallbackregister_base.h 
b/gnuradio-runtime/include/gnuradio/rpccallbackregister_base.h
index 3d2d4cc..814749f 100644
--- a/gnuradio-runtime/include/gnuradio/rpccallbackregister_base.h
+++ b/gnuradio-runtime/include/gnuradio/rpccallbackregister_base.h
@@ -1,9 +1,9 @@
 /* -*- c++ -*- */
-/* 
+/*
  * Copyright 2012 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
- * 
+ *
  * GNU Radio is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 3, or (at your option)
@@ -28,7 +28,7 @@
 
 typedef uint32_t DisplayType;
 
-// DisplayType Plotting types
+//! DisplayType Plotting types
 const uint32_t DISPNULL = 0x0000;
 const uint32_t DISPTIME = 0x0001;
 const uint32_t DISPXY   = 0x0002;
@@ -36,7 +36,7 @@ const uint32_t DISPPSD  = 0x0004;
 const uint32_t DISPSPEC = 0x0008;
 const uint32_t DISPRAST = 0x0010;
 
-// DisplayType Options
+//! DisplayType Options
 const uint32_t DISPOPTCPLX    = 0x0100;
 const uint32_t DISPOPTLOG     = 0x0200;
 const uint32_t DISPOPTSTEM    = 0x0400;
@@ -80,7 +80,7 @@ struct callbackregister_base
   class callback_t : public callback_base_t
   {
   public:
-    callback_t(T* callback_, priv_lvl_t priv_, 
+    callback_t(T* callback_, priv_lvl_t priv_,
               const std::string& units_, const DisplayType display_, const:: 
std::string& desc_,
               const pmt::pmt_t& min_, const pmt::pmt_t& max_, const 
pmt::pmt_t& def_) :
       callback_base_t(priv_, units_, display_, desc_, min_, max_, def_),
@@ -88,6 +88,12 @@ struct callbackregister_base
     {
     }
 
+    callback_t(T* callback_, priv_lvl_t priv_, const:: std::string& desc_) :
+      callback_base_t(priv_, "", 0, desc_, pmt::pmt_t(), pmt::pmt_t(), 
pmt::pmt_t()),
+      callback(callback_)
+    {
+    }
+
     Tsptr callback;
   };
 
diff --git a/gnuradio-runtime/include/gnuradio/rpcregisterhelpers.h 
b/gnuradio-runtime/include/gnuradio/rpcregisterhelpers.h
index 92adc0b..ce21b96 100644
--- a/gnuradio-runtime/include/gnuradio/rpcregisterhelpers.h
+++ b/gnuradio-runtime/include/gnuradio/rpcregisterhelpers.h
@@ -1,9 +1,9 @@
 /* -*- c++ -*- */
-/* 
- * Copyright 2012 Free Software Foundation, Inc.
+/*
+ * Copyright 2012,2014 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
- * 
+ *
  * GNU Radio is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 3, or (at your option)
@@ -32,8 +32,17 @@
 #include <gnuradio/rpcserver_base.h>
 #include <gnuradio/block_registry.h>
 
-// Base classes
-template<typename T, typename Tto> class rpcextractor_base
+
+/*********************************************************************
+ *   RPC Extractor Base Classes
+ ********************************************************************/
+
+/*!
+ *\brief Base class for registering a ControlPort Extractor. Acts as
+ *       a message acceptor.
+ */
+template<typename T, typename Tto>
+class rpcextractor_base
   : public virtual gr::messages::msg_accepter
 {
 public:
@@ -50,15 +59,45 @@ protected:
   void (T::*_func)(Tto);
 };
 
+template<typename T>
+class rpcextractor_base<T,void>
+  : public virtual gr::messages::msg_accepter
+{
+public:
+  rpcextractor_base(T* source, void (T::*func)()) :
+    _source(source), _func(func) {;}
+  ~rpcextractor_base() {;}
+
+  void post(pmt::pmt_t which_port, pmt::pmt_t msg) {
+    throw std::runtime_error("rpcextractor_base: no post defined for this data 
type.\n");
+  }
+
+protected:
+  T* _source;
+  void (T::*_func)();
+};
+
+/*!
+ * \brief Templated parent class for registering a ControlPort Extractor.
+ */
 template<typename T, typename Tto>
 class rpcbasic_extractor : public virtual rpcextractor_base<T,Tto>
 {
 public:
   rpcbasic_extractor(T* source, void (T::*func)(Tto)) :
-    rpcextractor_base<T,Tto>(source, func) 
+    rpcextractor_base<T,Tto>(source, func)
   {;}
 };
 
+
+/*********************************************************************
+ *   RPC Inserter Base Classes
+ ********************************************************************/
+
+/*!
+ * \brief Base class for registering a ControlPort Inserter. Produces a
+ *        message.
+ */
 template<typename T, typename Tfrom>
 class rpcinserter_base : public virtual gr::messages::msg_producer
 {
@@ -73,6 +112,11 @@ protected:
   Tfrom (T::*_func)();
 };
 
+
+/*!
+ * \brief Templated parent class for registering a ControlPort
+ * Inserter.
+ */
 template<typename T, typename Tfrom>
 class rpcbasic_inserter :
   public virtual rpcinserter_base<T,Tfrom>
@@ -86,14 +130,39 @@ public:
     : rpcinserter_base<T,Tfrom>(source, func)
   {;}
 
-  pmt::pmt_t retrieve() 
+  pmt::pmt_t retrieve()
   {
     return pmt::mp((rpcinserter_base<T,Tfrom>::
                    _source->*rpcinserter_base<T,Tfrom>::_func)());
   }
 };
 
-// Specialized Extractor Templates
+
+/*********************************************************************
+ *   RPC Specialized Extractors
+ ********************************************************************/
+
+/*!
+ * \brief Specialized extractor class to make calls to functions that
+ * do not take data (enable, reset, start, etc.).
+ */
+template<typename T>
+class rpcbasic_extractor<T,void> : public virtual rpcextractor_base<T,void>
+{
+public:
+  rpcbasic_extractor(T* source, void (T::*func)())
+    : rpcextractor_base<T,void>(source, func)
+  {;}
+
+  void post(pmt::pmt_t which_port, pmt::pmt_t msg)
+  {
+    (rpcextractor_base<T,void>::_source->*rpcextractor_base<T,void>::_func)();
+  }
+};
+
+/*!
+ * \brief Specialized extractor class for char data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,char> : public virtual rpcextractor_base<T,char>
 {
@@ -109,6 +178,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized extractor class for short data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,short> : public virtual rpcextractor_base<T,short>
 {
@@ -124,6 +196,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized extractor class for double data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,double> : public virtual rpcextractor_base<T,double>
 {
@@ -139,6 +214,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized extractor class for float data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,float> : public virtual rpcextractor_base<T,float>
 {
@@ -154,6 +232,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized extractor class for long data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,long> : public virtual rpcextractor_base<T,long>
 {
@@ -169,6 +250,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized extractor class for int data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,int> : public virtual rpcextractor_base<T,int>
 {
@@ -184,6 +268,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized extractor class for bool data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,bool> : public virtual rpcextractor_base<T,bool>
 {
@@ -199,6 +286,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized extractor class for complex (float) data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,std::complex<float> >
   : public virtual rpcextractor_base<T,std::complex<float> >
@@ -216,6 +306,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized extractor class for complex (double) data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,std::complex<double> >
   : public virtual rpcextractor_base<T,std::complex<double> >
@@ -232,6 +325,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized extractor class for string data.
+ */
 template<typename T>
 class rpcbasic_extractor<T,std::string>
   : public virtual rpcextractor_base<T,std::string>
@@ -244,10 +340,18 @@ public:
   void post(pmt::pmt_t which_port, pmt::pmt_t msg)
   {
     (rpcextractor_base<T,std::string>::
-     
_source->*rpcextractor_base<T,std::string>::_func)(pmt::symbol_to_string(msg)); 
+     
_source->*rpcextractor_base<T,std::string>::_func)(pmt::symbol_to_string(msg));
   }
 };
 
+
+/*********************************************************************
+ *   RPC Specialized Inserters
+ ********************************************************************/
+
+/*!
+ * \brief Specialized inserter class for uint64_t data.
+ */
 template<typename T>
 class rpcbasic_inserter<T,uint64_t> : public virtual 
rpcinserter_base<T,uint64_t>
 {
@@ -267,6 +371,9 @@ public:
   }
 };
 
+/*!
+ * \brief Specialized inserter class for vectors of signed char data.
+ */
 template<typename T>
 class rpcbasic_inserter<T,std::vector< signed char > >
   : public virtual rpcinserter_base<T,std::vector< signed char > >
@@ -284,11 +391,14 @@ public:
   {
     std::vector< signed char >
       vec((rpcinserter_base<T,std::vector< signed char > >::
-          _source->*rpcinserter_base<T,std::vector< signed char > 
>::_func)()); 
+          _source->*rpcinserter_base<T,std::vector< signed char > >::_func)());
     return pmt::init_s8vector(vec.size(), &vec[0]);
   }
 };
 
+/*!
+ * \brief Specialized inserter class for vectors of short data.
+ */
 template<typename T>
 class rpcbasic_inserter<T,std::vector< short > >
   : public virtual rpcinserter_base<T,std::vector< short > >
@@ -306,11 +416,14 @@ public:
   {
     std::vector< short >
       vec((rpcinserter_base<T,std::vector< short > >::
-          _source->*rpcinserter_base<T,std::vector< short > >::_func)()); 
+          _source->*rpcinserter_base<T,std::vector< short > >::_func)());
     return pmt::init_s16vector(vec.size(), &vec[0]);
   }
 };
 
+/*!
+ * \brief Specialized inserter class for vectors of int data.
+ */
 template<typename T>
 class rpcbasic_inserter<T,std::vector< int > >
   : public virtual rpcinserter_base<T,std::vector< int > >
@@ -328,11 +441,14 @@ public:
   {
     std::vector< int >
       vec((rpcinserter_base<T,std::vector<int > >::
-          _source->*rpcinserter_base<T,std::vector< int > >::_func)()); 
+          _source->*rpcinserter_base<T,std::vector< int > >::_func)());
     return pmt::init_s32vector(vec.size(), &vec[0]);
   }
 };
 
+/*!
+ * \brief Specialized inserter class for vectors of complex (float) data.
+ */
 template<typename T>
 class rpcbasic_inserter<T,std::vector< std::complex<float> > >
   : public virtual rpcinserter_base<T,std::vector< std::complex<float> > >
@@ -350,11 +466,14 @@ public:
   {
     std::vector< std::complex<float> >
       vec((rpcinserter_base<T,std::vector<std::complex<float> > >::
-          _source->*rpcinserter_base<T,std::vector< std::complex<float> > 
>::_func)()); 
+          _source->*rpcinserter_base<T,std::vector< std::complex<float> > 
>::_func)());
     return pmt::init_c32vector(vec.size(), &vec[0]);
   }
 };
 
+/*!
+ * \brief Specialized inserter class for vectors of float data.
+ */
 template<typename T>
 class rpcbasic_inserter<T,std::vector< float> >
   : public virtual rpcinserter_base<T,std::vector< float > >
@@ -363,7 +482,7 @@ public:
   rpcbasic_inserter(T* source, std::vector<float> (T::*func)() const)
     : rpcinserter_base<T,std::vector<float > >(source, func)
   {;}
-  
+
   rpcbasic_inserter(T* source, std::vector<float> (T::*func)())
     : rpcinserter_base<T,std::vector<float> >(source, func)
   {;}
@@ -371,44 +490,50 @@ public:
   pmt::pmt_t retrieve()
   {
     std::vector< float > vec((rpcinserter_base<T,std::vector<float> >::
-             _source->*rpcinserter_base<T,std::vector< float> >::_func)()); 
+             _source->*rpcinserter_base<T,std::vector< float> >::_func)());
     return pmt::init_f32vector(vec.size(), &vec[0]);
   }
 };
 
-template<typename T> 
-class rpcbasic_inserter<T,std::vector< uint8_t> > 
+/*!
+ * \brief Specialized inserter class for vectors of uint8_t data.
+ */
+template<typename T>
+class rpcbasic_inserter<T,std::vector< uint8_t> >
   : public virtual rpcinserter_base<T,std::vector< uint8_t > > {
 public:
-  rpcbasic_inserter(T* source, std::vector<uint8_t> (T::*func)() const) 
-    : rpcinserter_base<T,std::vector<uint8_t > >(source, func) 
+  rpcbasic_inserter(T* source, std::vector<uint8_t> (T::*func)() const)
+    : rpcinserter_base<T,std::vector<uint8_t > >(source, func)
   {;}
 
-  rpcbasic_inserter(T* source, std::vector<uint8_t> (T::*func)()) 
-    : rpcinserter_base<T,std::vector<uint8_t> >(source, func) 
+  rpcbasic_inserter(T* source, std::vector<uint8_t> (T::*func)())
+    : rpcinserter_base<T,std::vector<uint8_t> >(source, func)
   {;}
 
-  pmt::pmt_t retrieve() 
+  pmt::pmt_t retrieve()
   {
     std::vector< uint8_t > vec((rpcinserter_base<T,std::vector<uint8_t> >::
         _source->*rpcinserter_base<T,std::vector< uint8_t> >::_func)());
-    return pmt::init_u8vector(vec.size(), &vec[0]); 
+    return pmt::init_u8vector(vec.size(), &vec[0]);
   }
 };
 
-template<typename T> 
-class rpcbasic_inserter<T,std::complex<float> > 
+/*!
+ * \brief Specialized inserter class for complex (float) data.
+ */
+template<typename T>
+class rpcbasic_inserter<T,std::complex<float> >
   : public virtual rpcinserter_base<T,std::complex<float > > {
 public:
-  rpcbasic_inserter(T* source, std::complex<float> (T::*func)() const) 
-    : rpcinserter_base<T,std::complex<float> >(source, func) 
+  rpcbasic_inserter(T* source, std::complex<float> (T::*func)() const)
+    : rpcinserter_base<T,std::complex<float> >(source, func)
   {;}
 
-  rpcbasic_inserter(T* source, std::complex<float> (T::*func)()) 
-    : rpcinserter_base<T,std::complex<float> >(source, func) 
+  rpcbasic_inserter(T* source, std::complex<float> (T::*func)())
+    : rpcinserter_base<T,std::complex<float> >(source, func)
   {;}
 
-  pmt::pmt_t retrieve() 
+  pmt::pmt_t retrieve()
   {
     std::complex<float > k((rpcinserter_base<T,std::complex<float> >::
                              _source->*rpcinserter_base<T,std::complex<float> 
>::_func)());
@@ -416,16 +541,19 @@ public:
   }
 };
 
-template<typename T> 
-class rpcbasic_inserter<T,std::complex<double> > 
+/*!
+ * \brief Specialized inserter class for complex (double) data.
+ */
+template<typename T>
+class rpcbasic_inserter<T,std::complex<double> >
   : public virtual rpcinserter_base<T,std::complex<double > > {
 public:
-  rpcbasic_inserter(T* source, std::complex<double> (T::*func)() const) 
-    : rpcinserter_base<T,std::complex<double> >(source, func) 
+  rpcbasic_inserter(T* source, std::complex<double> (T::*func)() const)
+    : rpcinserter_base<T,std::complex<double> >(source, func)
   {;}
 
-  rpcbasic_inserter(T* source, std::complex<double> (T::*func)()) 
-    : rpcinserter_base<T,std::complex<double> >(source, func) 
+  rpcbasic_inserter(T* source, std::complex<double> (T::*func)())
+    : rpcinserter_base<T,std::complex<double> >(source, func)
   {;}
 
   pmt::pmt_t retrieve()
@@ -436,6 +564,9 @@ public:
   }
 };
 
+/*!
+ * \brief Base class for registering a ControlPort function.
+ */
 template <typename T>
 struct rpc_register_base
 {
@@ -443,7 +574,9 @@ struct rpc_register_base
 protected: static int count;
 };
 
-// Base class to inherit from and create universal shared pointers.
+/*!
+ * Base class to inherit from and create universal shared pointers.
+ */
 class rpcbasic_base
 {
 public:
@@ -451,17 +584,80 @@ public:
   virtual ~rpcbasic_base() {};
 };
 
+
 typedef boost::shared_ptr<rpcbasic_base> rpcbasic_sptr;
 
+
+
+/*********************************************************************
+ *   RPC Register Set Classes
+ ********************************************************************/
+
+/*!
+ * \brief Registers a 'set' function to set a parameter over
+ * ControlPort.
+ *
+ * \details
+ *
+ * This class allows us to remotely set a value or parameter of the
+ * block over ControlPort. The set occurs by calling a setter accessor
+ * function of the class, usually set_[variable](), which is passed in
+ * as \p function.
+ *
+ * We can set the (expected) minimum (\p min), maximum (\p max), and
+ * default (\p def) of the variables being set. These values are not
+ * enforced, however, but can be useful for setting up graphs and
+ * other ways of bounding the data.
+ *
+ * This class also allows us to provide information to the user about
+ * the variable being set, such as an appropriate unit (\p units_) as
+ * well as a description (\p desc_) about what the variable does.
+ *
+ * The privilege (\p minpriv_) level is the minimum privilege level a
+ * remote must identify with to be able to call this function.
+ *
+ * We also provide display hints (\p display_), which can be used by
+ * the ControlPort client application to know how to best display or
+ * even print the data. This is a mask of options for variables set in
+ * rpccallbackregister_base.h. The mask is defined by one of the
+ * "DisplayType Plotting Types" and or'd with any of the "DisplayType
+ * Options" features. See "Display Options" in \ref page_ctrlport for
+ * details.
+ */
 template<typename T, typename Tto>
 struct rpcbasic_register_set : public rpcbasic_base
 {
-  // Function used to add a 'set' RPC call using a basic_block's alias.
+  /*!
+   * \brief Adds the ability to set the variable over ControlPort.
+   *
+   * \details
+   *
+   * This constructor is specifically for gr::block's to use to add
+   * settable variables to ControlPort. Generally meant to be used
+   * in gr::block::setup_rpc.
+   *
+   * Uses the block's alias to create the ControlPort interface. This
+   * alias is cross-referenced by the global_block_registry (static
+   * variable of type gr::block_registry) to get the pointer to the
+   * block.
+   *
+   * \param block_alias  Block's alias; use alias() to get it from the block.
+   * \param functionbase The name of the function that we'll access over 
ControlPort
+   * \param function     A function pointer to the real function accessed when 
called
+   *                     something like: &[block class]\::set_[variable]()
+   * \param min          Expected minimum value the parameter can hold
+   * \param max          Expected maximum value the parameter can hold
+   * \param def          Expected default value the parameter can hold
+   * \param units_       A string to describe what units to represent the 
variable with
+   * \param desc_        A string to describing the variable.
+   * \param minpriv_     The required minimum privilege level
+   * \param display_     The display mask
+   */
   rpcbasic_register_set(const std::string& block_alias,
                        const char* functionbase,
-                       void (T::*function)(Tto), 
+                       void (T::*function)(Tto),
                        const pmt::pmt_t &min, const pmt::pmt_t &max, const 
pmt::pmt_t &def,
-                       const char* units_ = "", 
+                       const char* units_ = "",
                        const char* desc_ = "",
                        priv_lvl_t minpriv_ = RPC_PRIVLVL_MIN,
                        DisplayType display_ = DISPNULL)
@@ -476,7 +672,7 @@ struct rpcbasic_register_set : public rpcbasic_base
     d_object = 
dynamic_cast<T*>(global_block_registry.block_lookup(pmt::intern(block_alias)).get());
 #ifdef RPCSERVER_ENABLED
     callbackregister_base::configureCallback_t
-      extractor(new rpcbasic_extractor<T,Tto>(d_object, function), 
+      extractor(new rpcbasic_extractor<T,Tto>(d_object, function),
                minpriv_, std::string(units_),
                display_, std::string(desc_), min, max, def);
     std::ostringstream oss(std::ostringstream::out);
@@ -487,13 +683,35 @@ struct rpcbasic_register_set : public rpcbasic_base
 #endif
   }
 
-  // Function used to add a 'set' RPC call using a name and the object
+  /*!
+   * \brief Adds the ability to set the variable over ControlPort.
+   *
+   * \details
+   *
+   * Allows us to add non gr::block related objects to
+   * ControlPort. Instead of using the block's alias, we give it a \p
+   * name and the actual pointer to the object as \p obj. We just need
+   * to make sure that the pointer to this object is always valid.
+   *
+   * \param name         Name of the object being set up for ControlPort access
+   * \param functionbase The name of the function that we'll access over 
ControlPort
+   * \param obj          A pointer to the object itself
+   * \param function     A function pointer to the real function accessed when 
called
+   *                     something like: &[block class]\::set_[variable]()
+   * \param min          Expected minimum value the parameter can hold
+   * \param max          Expected maximum value the parameter can hold
+   * \param def          Expected default value the parameter can hold
+   * \param units_       A string to describe what units to represent the 
variable with
+   * \param desc_        A string to describing the variable.
+   * \param minpriv_     The required minimum privilege level
+   * \param display_     The display mask
+   */
   rpcbasic_register_set(const std::string& name,
                        const char* functionbase,
                         T* obj,
-                       void (T::*function)(Tto), 
+                       void (T::*function)(Tto),
                        const pmt::pmt_t &min, const pmt::pmt_t &max, const 
pmt::pmt_t &def,
-                       const char* units_ = "", 
+                       const char* units_ = "",
                        const char* desc_ = "",
                        priv_lvl_t minpriv_ = RPC_PRIVLVL_MIN,
                        DisplayType display_ = DISPNULL)
@@ -508,7 +726,7 @@ struct rpcbasic_register_set : public rpcbasic_base
     d_object = obj;
 #ifdef RPCSERVER_ENABLED
     callbackregister_base::configureCallback_t
-      extractor(new rpcbasic_extractor<T,Tto>(d_object, function), 
+      extractor(new rpcbasic_extractor<T,Tto>(d_object, function),
                minpriv_, std::string(units_),
                display_, std::string(desc_), min, max, def);
     std::ostringstream oss(std::ostringstream::out);
@@ -553,17 +771,209 @@ private:
 };
 
 
+/*********************************************************************
+ *   RPC Register Trigger Classes
+ ********************************************************************/
+
+/*!
+ * \brief Registers a 'trigger' function to trigger an action over
+ * ControlPort.
+ *
+ * \details
+ *
+ * This class allows us to set up triggered events or function calls
+ * over ControlPort. When used from a ControlPort client, the \p
+ * function established here will be activated. Generally, this is
+ * meant to enable some kind of trigger or action that a block or
+ * object will perform, such as a reset, start, stop, etc.
+ *
+ * Simpler than the rpcbasic_register_set class, the constructor here
+ * only takes a few parameters, mostly because there is not actual
+ * variable associated with these function calls. It takes in the
+ * information to set up the pointer to the object that has the \p
+ * function, a ControlPort name (\p functionbase) for the triggered
+ * action, a description (\p desc_), and a privilege level (\p
+ * minpriv_).
+ */
+template<typename T>
+struct rpcbasic_register_trigger : public rpcbasic_base
+{
+  /*!
+   * \brief Adds the ability to trigger a function over ControlPort.
+   *
+   * \details
+   *
+   * This constructor is specifically for gr::block's to use to add
+   * trigger functions to ControlPort. Generally meant to be used
+   * in gr::block::setup_rpc.
+   *
+   * Uses the block's alias to create the ControlPort interface. This
+   * alias is cross-referenced by the global_block_registry (static
+   * variable of type gr::block_registry) to get the pointer to the
+   * block.
+   *
+   * \param block_alias  Block's alias; use alias() to get it from the block.
+   * \param functionbase The name of the function that we'll access over 
ControlPort
+   * \param function     A function pointer to the real function accessed when 
called
+   *                     something like: &[block class]\::set_[variable]
+   * \param desc_        A string to describing the variable.
+   * \param minpriv_     The required minimum privilege level
+   */
+  rpcbasic_register_trigger(const std::string& block_alias,
+                            const char* functionbase,
+                            void (T::*function)(),
+                            const char* desc_ = "",
+                            priv_lvl_t minpriv_ = RPC_PRIVLVL_MIN)
+  {
+    d_desc = desc_;
+    d_minpriv = minpriv_;
+    d_object = 
dynamic_cast<T*>(global_block_registry.block_lookup(pmt::intern(block_alias)).get());
+#ifdef RPCSERVER_ENABLED
+    callbackregister_base::configureCallback_t
+      extractor(new rpcbasic_extractor<T,void>(d_object, function),
+               minpriv_, std::string(desc_));
+    std::ostringstream oss(std::ostringstream::out);
+    oss << block_alias << "::" << functionbase;
+    d_id = oss.str();
+    //std::cerr << "REGISTERING TRIGGER: " << d_id << "  " << desc_ << 
std::endl;
+    rpcmanager::get()->i()->registerConfigureCallback(d_id, extractor);
+#endif
+  }
+
+  /*!
+   * \brief Adds the ability to trigger a function over ControlPort.
+   *
+   * \details
+   *
+   * Allows us to add non gr::block related objects to
+   * ControlPort. Instead of using the block's alias, we give it a \p
+   * name and the actual pointer to the object as \p obj. We just need
+   * to make sure that the pointer to this object is always valid.
+   *
+   * \param name         Name of the object being set up for ControlPort access
+   * \param functionbase The name of the function that we'll access over 
ControlPort
+   * \param obj          A pointer to the object itself
+   * \param function     A function pointer to the real function accessed when 
called
+   *                     something like: &[block class]\::set_[variable]
+   * \param desc_        A string to describing the variable.
+   * \param minpriv_     The required minimum privilege level
+   */
+  rpcbasic_register_trigger(const std::string& name,
+                            const char* functionbase,
+                            T* obj,
+                            void (T::*function)(),
+                            const char* desc_ = "",
+                            priv_lvl_t minpriv_ = RPC_PRIVLVL_MIN)
+  {
+    d_desc = desc_;
+    d_minpriv = minpriv_;
+    d_object = obj;
+#ifdef RPCSERVER_ENABLED
+    callbackregister_base::configureCallback_t
+      extractor(new rpcbasic_extractor<T,void>(d_object, function),
+               minpriv_, std::string(desc_));
+    std::ostringstream oss(std::ostringstream::out);
+    oss << name << "::" << functionbase;
+    d_id = oss.str();
+    //std::cerr << "REGISTERING TRIGGER: " << d_id << "  " << desc_ << 
std::endl;
+    rpcmanager::get()->i()->registerConfigureCallback(d_id, extractor);
+#endif
+  }
+
+  ~rpcbasic_register_trigger()
+  {
+#ifdef RPCSERVER_ENABLED
+    rpcmanager::get()->i()->unregisterConfigureCallback(d_id);
+#endif
+  }
+
+
+  std::string description() const { return d_desc; }
+  priv_lvl_t privilege_level() const { return d_minpriv; }
+
+  void description(std::string d) { d_desc = d; }
+  void privilege_level(priv_lvl_t p) { d_minpriv = p; }
+
+private:
+  std::string d_id;
+  std::string d_desc;
+  priv_lvl_t d_minpriv;
+  T *d_object;
+};
+
+
+
+/*********************************************************************
+ *   RPC Register Get Classes
+ ********************************************************************/
+
+/*!
+ * \brief Registers a 'get' function to get a parameter over
+ * ControlPort.
+ *
+ * \details
+ *
+ * This class allows us to remotely get a value or parameter of the
+ * block over ControlPort. The get occurs by calling a getter accessor
+ * function of the class, usually [variable](), which is passed in
+ * as \p function.
+ *
+ * We can set the (expected) minimum (\p min), maximum (\p max), and
+ * default (\p def) of the variables we will get. These values are not
+ * enforced, however, but can be useful for setting up graphs and
+ * other ways of bounding the data.
+ *
+ * This class also allows us to provide information to the user about
+ * the variable, such as an appropriate unit (\p units_) as well as a
+ * description (\p desc_) about what the variable does.
+ *
+ * The privilege (\p minpriv_) level is the minimum privilege level a
+ * remote must identify with to be able to call this function.
+ *
+ * We also provide display hints (\p display_), which can be used by
+ * the ControlPort client application to know how to best display or
+ * even print the data. This is a mask of options for variables set in
+ * rpccallbackregister_base.h. The mask is defined by one of the
+ * "DisplayType Plotting Types" and or'd with any of the "DisplayType
+ * Options" features. See "Display Options" in \ref page_ctrlport for
+ * details.
+ */
 template<typename T, typename Tfrom>
 class rpcbasic_register_get : public rpcbasic_base
 {
 public:
-  // Function used to add a 'set' RPC call using a basic_block's alias.
-  // primary constructor to allow for T get() functions
+
+  /*!
+   * \brief Adds the ability to get the variable over ControlPort.
+   *
+   * \details
+   *
+   * This constructor is specifically for gr::block's to use to add
+   * gettable variables to ControlPort. Generally meant to be used
+   * in gr::block::setup_rpc.
+   *
+   * Uses the block's alias to create the ControlPort interface. This
+   * alias is cross-referenced by the global_block_registry (static
+   * variable of type gr::block_registry) to get the pointer to the
+   * block.
+   *
+   * \param block_alias  Block's alias; use alias() to get it from the block.
+   * \param functionbase The name of the function that we'll access over 
ControlPort
+   * \param function     A function pointer to the real function accessed when 
called
+   *                     something like: &[block class]\::[variable]()
+   * \param min          Expected minimum value the parameter can hold
+   * \param max          Expected maximum value the parameter can hold
+   * \param def          Expected default value the parameter can hold
+   * \param units_       A string to describe what units to represent the 
variable with
+   * \param desc_        A string to describing the variable.
+   * \param minpriv_     The required minimum privilege level
+   * \param display_     The display mask
+   */
   rpcbasic_register_get(const std::string& block_alias,
                        const char* functionbase,
-                       Tfrom (T::*function)(), 
+                       Tfrom (T::*function)(),
                        const pmt::pmt_t &min, const pmt::pmt_t &max, const 
pmt::pmt_t &def,
-                       const char* units_ = "", 
+                       const char* units_ = "",
                        const char* desc_ = "",
                        priv_lvl_t minpriv_ = RPC_PRIVLVL_MIN,
                        DisplayType display_ = DISPNULL)
@@ -578,7 +988,7 @@ public:
     d_object = 
dynamic_cast<T*>(global_block_registry.block_lookup(pmt::intern(block_alias)).get());
 #ifdef RPCSERVER_ENABLED
     callbackregister_base::queryCallback_t
-      inserter(new rpcbasic_inserter<T,Tfrom>(d_object, function), 
+      inserter(new rpcbasic_inserter<T,Tfrom>(d_object, function),
               minpriv_, std::string(units_), display_, std::string(desc_), 
min, max, def);
     std::ostringstream oss(std::ostringstream::out);
     oss << block_alias << "::" << functionbase;
@@ -588,17 +998,20 @@ public:
 #endif
   }
 
-       
-  // alternate constructor to allow for T get() const functions
+
+  /*!
+   * \brief Same as rpcbasic_register_get::rpcbasic_register_get that allows 
using
+   * '[variable]() const' getter functions.
+   */
   rpcbasic_register_get(const std::string& block_alias,
                        const char* functionbase,
-                       Tfrom (T::*function)() const, 
+                       Tfrom (T::*function)() const,
                        const pmt::pmt_t &min, const pmt::pmt_t &max, const 
pmt::pmt_t &def,
-                       const char* units_ = "", 
+                       const char* units_ = "",
                        const char* desc_ = "",
                        priv_lvl_t minpriv_ = RPC_PRIVLVL_MIN,
                        DisplayType display_ = DISPNULL)
-  { 
+  {
     d_min = min;
     d_max = max;
     d_def = def;
@@ -609,7 +1022,7 @@ public:
     d_object = 
dynamic_cast<T*>(global_block_registry.block_lookup(pmt::intern(block_alias)).get());
 #ifdef RPCSERVER_ENABLED
     callbackregister_base::queryCallback_t
-      inserter(new rpcbasic_inserter<T,Tfrom>(d_object, (Tfrom 
(T::*)())function), 
+      inserter(new rpcbasic_inserter<T,Tfrom>(d_object, (Tfrom 
(T::*)())function),
               minpriv_, std::string(units_), display_, std::string(desc_), 
min, max, def);
     std::ostringstream oss(std::ostringstream::out);
     oss << block_alias << "::" << functionbase;
@@ -619,14 +1032,36 @@ public:
 #endif
   }
 
-  // Function used to add a 'set' RPC call using a name and the object
-  // primary constructor to allow for T get() functions
+
+  /*!
+   * \brief Adds the ability to get the variable over ControlPort.
+   *
+   * \details
+   *
+   * Allows us to add non gr::block related objects to
+   * ControlPort. Instead of using the block's alias, we give it a \p
+   * name and the actual pointer to the object as \p obj. We just need
+   * to make sure that the pointer to this object is always valid.
+   *
+   * \param name         Name of the object being set up for ControlPort access
+   * \param functionbase The name of the function that we'll access over 
ControlPort
+   * \param obj          A pointer to the object itself
+   * \param function     A function pointer to the real function accessed when 
called
+   *                     something like: &[block class]\::set_[variable]()
+   * \param min          Expected minimum value the parameter can hold
+   * \param max          Expected maximum value the parameter can hold
+   * \param def          Expected default value the parameter can hold
+   * \param units_       A string to describe what units to represent the 
variable with
+   * \param desc_        A string to describing the variable.
+   * \param minpriv_     The required minimum privilege level
+   * \param display_     The display mask
+   */
   rpcbasic_register_get(const std::string& name,
                        const char* functionbase,
                         T* obj,
-                       Tfrom (T::*function)(), 
+                       Tfrom (T::*function)(),
                        const pmt::pmt_t &min, const pmt::pmt_t &max, const 
pmt::pmt_t &def,
-                       const char* units_ = "", 
+                       const char* units_ = "",
                        const char* desc_ = "",
                        priv_lvl_t minpriv_ = RPC_PRIVLVL_MIN,
                        DisplayType display_ = DISPNULL)
@@ -641,7 +1076,7 @@ public:
     d_object = obj;
 #ifdef RPCSERVER_ENABLED
     callbackregister_base::queryCallback_t
-      inserter(new rpcbasic_inserter<T,Tfrom>(d_object, function), 
+      inserter(new rpcbasic_inserter<T,Tfrom>(d_object, function),
               minpriv_, std::string(units_), display_, std::string(desc_), 
min, max, def);
     std::ostringstream oss(std::ostringstream::out);
     oss << name << "::" << functionbase;
@@ -651,18 +1086,21 @@ public:
 #endif
   }
 
-       
-  // alternate constructor to allow for T get() const functions
+
+  /*!
+   * \brief Same as above that allows using '[variable]() const'
+   * getter functions.
+   */
   rpcbasic_register_get(const std::string& name,
                        const char* functionbase,
                         T* obj,
-                       Tfrom (T::*function)() const, 
+                       Tfrom (T::*function)() const,
                        const pmt::pmt_t &min, const pmt::pmt_t &max, const 
pmt::pmt_t &def,
-                       const char* units_ = "", 
+                       const char* units_ = "",
                        const char* desc_ = "",
                        priv_lvl_t minpriv_ = RPC_PRIVLVL_MIN,
                        DisplayType display_ = DISPNULL)
-  { 
+  {
     d_min = min;
     d_max = max;
     d_def = def;
@@ -673,7 +1111,7 @@ public:
     d_object = obj;
 #ifdef RPCSERVER_ENABLED
     callbackregister_base::queryCallback_t
-      inserter(new rpcbasic_inserter<T,Tfrom>(d_object, (Tfrom 
(T::*)())function), 
+      inserter(new rpcbasic_inserter<T,Tfrom>(d_object, (Tfrom 
(T::*)())function),
               minpriv_, std::string(units_), display_, std::string(desc_), 
min, max, def);
     std::ostringstream oss(std::ostringstream::out);
     oss << name << "::" << functionbase;
@@ -715,23 +1153,64 @@ private:
   T *d_object;
 };
 
-/*
- * This class can wrap a pre-existing variable type for you
- * it will define the getter and rpcregister call for you.
- * 
- * It should be used for read-only getters.
+
+
+/*********************************************************************
+ *   RPC Register Variable Classes
+ ********************************************************************/
+
+/*!
+ * \brief Registers a read-only function to get a parameter over ControlPort.
+ *
+ * \details
+ *
+ * This class allows us to remotely get a value or parameter of the
+ * block over ControlPort. Unlike the rpcbasic_register_get class,
+ * this version is passed the variable directly and establishes a
+ * getter for us, so there is no need to have a getter function
+ * already in the object.
+ *
+ * This version is for read-only get access.
+ *
+ * We can set the (expected) minimum (\p min), maximum (\p max), and
+ * default (\p def) of the variables we will get. These values are not
+ * enforced, however, but can be useful for setting up graphs and
+ * other ways of bounding the data.
+ *
+ * This class also allows us to provide information to the user about
+ * the variable, such as an appropriate unit (\p units_) as well as a
+ * description (\p desc_) about what the variable does.
  *
+ * The privilege (\p minpriv_) level is the minimum privilege level a
+ * remote must identify with to be able to call this function.
+ *
+ * We also provide display hints (\p display_), which can be used by
+ * the ControlPort client application to know how to best display or
+ * even print the data. This is a mask of options for variables set in
+ * rpccallbackregister_base.h. The mask is defined by one of the
+ * "DisplayType Plotting Types" and or'd with any of the "DisplayType
+ * Options" features. See "Display Options" in \ref page_ctrlport for
+ * details.
  */
 template<typename Tfrom>
-class rpcbasic_register_variable : public rpcbasic_base
+class rpcbasic_register_variable
+  : public rpcbasic_base
 {
 protected:
   rpcbasic_register_get< rpcbasic_register_variable<Tfrom>, Tfrom > d_rpc_reg;
   Tfrom *d_variable;
   Tfrom get() { return *d_variable; }
+
 public:
-  // empty constructor which should never be called but needs to exist for ues 
in varous STL data structures
-  void setptr(Tfrom* _variable){  
rpcbasic_register_variable<Tfrom>::d_variable = _variable; }
+
+  void setptr(Tfrom* _variable)
+  {
+    rpcbasic_register_variable<Tfrom>::d_variable = _variable;
+  }
+
+  /*! Empty constructor which should never be called but needs to
+   * exist for ues in varous STL data structures
+   */
   rpcbasic_register_variable() :
     d_rpc_reg("FAIL", "FAIL", this, &rpcbasic_register_variable::get,
              pmt::PMT_NIL, pmt::PMT_NIL, pmt::PMT_NIL, DISPNULL,
@@ -741,6 +1220,24 @@ public:
     throw std::runtime_error("ERROR: rpcbasic_register_variable called with no 
args. If this happens, someone has tried to use rpcbasic_register_variable 
incorrectly.");
   };
 
+  /*!
+   * \brief Adds the ability to get the variable over ControlPort.
+   *
+   * \details
+   *
+   * Creates a new getter accessor function to read \p variable.
+   *
+   * \param namebase     Name of the object being set up for ControlPort access
+   * \param functionbase The name of the function that we'll access over 
ControlPort
+   * \param variable     A pointer to the variable, possibly as a member of a 
class
+   * \param min          Expected minimum value the parameter can hold
+   * \param max          Expected maximum value the parameter can hold
+   * \param def          Expected default value the parameter can hold
+   * \param units_       A string to describe what units to represent the 
variable with
+   * \param desc_        A string to describing the variable.
+   * \param minpriv_     The required minimum privilege level
+   * \param display_     The display mask
+   */
   rpcbasic_register_variable(const std::string& namebase,
                             const char* functionbase,
                             Tfrom *variable,
@@ -748,7 +1245,7 @@ public:
                             const char* units_ = "",
                             const char* desc_ = "",
                             priv_lvl_t minpriv_ = RPC_PRIVLVL_MIN,
-                            DisplayType display_=DISPNULL) :
+                            DisplayType display_ = DISPNULL) :
     d_rpc_reg(namebase, functionbase, this, &rpcbasic_register_variable::get,
              min, max, def, units_, desc_, minpriv_, display_),
     d_variable(variable)
@@ -757,18 +1254,86 @@ public:
   }
 };
 
-template<typename Tfrom> class rpcbasic_register_variable_rw : public 
rpcbasic_register_variable<Tfrom> {
-  private:
-    rpcbasic_register_set< rpcbasic_register_variable_rw<Tfrom>, Tfrom > 
d_rpc_regset;
-  public:
-    // empty constructor which should never be called but needs to exist for 
ues in varous STL data structures
-    rpcbasic_register_variable_rw()  :
-            
d_rpc_regset("FAIL","FAIL",this,&rpcbasic_register_variable<Tfrom>::get,pmt::PMT_NIL,pmt::PMT_NIL,pmt::PMT_NIL,DISPNULL,"FAIL","FAIL",RPC_PRIVLVL_MIN)
-        {
-        throw std::runtime_error("ERROR: rpcbasic_register_variable_rw called 
with no args. if this happens someone used rpcbasic_register_variable_rw 
incorrectly.\n");
-        };
-    void set(Tfrom _variable){  
*(rpcbasic_register_variable<Tfrom>::d_variable) = _variable; }
-    rpcbasic_register_variable_rw(
+
+/*!
+ * \brief Registers a read/write function to get and set a parameter
+ * over ControlPort.
+ *
+ * \details
+ *
+ * This class allows us to remotely get and/or set a value or
+ * parameter of the block over ControlPort. Unlike the
+ * rpcbasic_register_get class, this version is passed the variable
+ * directly and establishes a getter for us, so there is no need to
+ * have a getter function already in the object.
+ *
+ * This version establishes both get and set functions and so provides
+ * read/write access to the variable.
+ *
+ * We can set the (expected) minimum (\p min), maximum (\p max), and
+ * default (\p def) of the variables we will get. These values are not
+ * enforced, however, but can be useful for setting up graphs and
+ * other ways of bounding the data.
+ *
+ * This class also allows us to provide information to the user about
+ * the variable, such as an appropriate unit (\p units_) as well as a
+ * description (\p desc_) about what the variable does.
+ *
+ * The privilege (\p minpriv_) level is the minimum privilege level a
+ * remote must identify with to be able to call this function.
+ *
+ * We also provide display hints (\p display_), which can be used by
+ * the ControlPort client application to know how to best display or
+ * even print the data. This is a mask of options for variables set in
+ * rpccallbackregister_base.h. The mask is defined by one of the
+ * "DisplayType Plotting Types" and or'd with any of the "DisplayType
+ * Options" features. See "Display Options" in \ref page_ctrlport for
+ * details.
+ */
+template<typename Tfrom>
+class rpcbasic_register_variable_rw
+  : public rpcbasic_register_variable<Tfrom>
+{
+private:
+  rpcbasic_register_set< rpcbasic_register_variable_rw<Tfrom>, Tfrom > 
d_rpc_regset;
+
+public:
+  /*! Empty constructor which should never be called but needs to
+   *  exist for ues in varous STL data structures.
+   */
+  rpcbasic_register_variable_rw()  :
+    d_rpc_regset("FAIL", "FAIL", this,
+                 &rpcbasic_register_variable<Tfrom>::get,
+                 pmt::PMT_NIL, pmt::PMT_NIL, pmt::PMT_NIL,
+                 DISPNULL, "FAIL", "FAIL", RPC_PRIVLVL_MIN)
+  {
+    throw std::runtime_error("ERROR: rpcbasic_register_variable_rw called with 
no args. if this happens someone used rpcbasic_register_variable_rw 
incorrectly.\n");
+  };
+
+  void set(Tfrom _variable)
+  {
+    *(rpcbasic_register_variable<Tfrom>::d_variable) = _variable;
+  }
+
+  /*!
+   * \brief Adds the ability to set and get the variable over ControlPort.
+   *
+   * \details
+   *
+   * Creates new getter and setter accessor functions to read and write \p 
variable.
+   *
+   * \param namebase     Name of the object being set up for ControlPort access
+   * \param functionbase The name of the function that we'll access over 
ControlPort
+   * \param variable     A pointer to the variable, possibly as a member of a 
class
+   * \param min          Expected minimum value the parameter can hold
+   * \param max          Expected maximum value the parameter can hold
+   * \param def          Expected default value the parameter can hold
+   * \param units_       A string to describe what units to represent the 
variable with
+   * \param desc_        A string to describing the variable.
+   * \param minpriv_     The required minimum privilege level
+   * \param display_     The display mask
+   */
+  rpcbasic_register_variable_rw(
         const std::string& namebase,
         const char* functionbase,
         Tfrom *variable,
@@ -776,12 +1341,15 @@ template<typename Tfrom> class 
rpcbasic_register_variable_rw : public rpcbasic_r
         const char* units_ = "",
         const char* desc_ = "",
         priv_lvl_t minpriv = RPC_PRIVLVL_MIN,
-        DisplayType display_=DISPNULL) :
-            
rpcbasic_register_variable<Tfrom>(namebase,functionbase,variable,min,max,def,units_,desc_),
-            
d_rpc_regset(namebase,functionbase,this,&rpcbasic_register_variable_rw::set,min,max,def,units_,desc_,minpriv,display_)
-         {
-        // no action
-        }
+        DisplayType display_=DISPNULL)
+    : rpcbasic_register_variable<Tfrom>(namebase, functionbase, variable,
+                                        min, max, def, units_, desc_),
+      d_rpc_regset(namebase, functionbase, this,
+                   &rpcbasic_register_variable_rw::set,
+                   min, max, def, units_, desc_, minpriv, display_)
+  {
+    // no action
+  }
 };