tags: adds get_tags_in_window helper function for handling tags. Also updates some docs.

author: Tom Rondeau <tom@trondeau.com> 2014-02-23 11:25:57 -0500
committer: Tom Rondeau <tom@trondeau.com> 2014-02-23 11:25:57 -0500
commit: b5fcc18523caeafebbf117cf2c838e7974856966 (patch)
tree: aac43972eb74614cded00b37d2d76c9113fa66a2
parent: 77c36d3cc3bb61581621dd61aab97a9b5d1b044e (diff)
6 files changed, 134 insertions, 37 deletions
diff --git a/docs/doxygen/other/stream_tags.dox b/docs/doxygen/other/stream_tags.dox
index 2a03c9629c..851740984e 100644
--- a/docs/doxygen/other/stream_tags.dox
+++ b/docs/doxygen/other/stream_tags.dox
@@ -63,15 +63,26 @@ at <em>nitems_written(0)+i</em> for the 0th output port.
 The stream tags API consists of four functions, two to add and two to
 get the stream tags. These functions are:
 
-\li add_item_tag: Adds an item tag to a particular output port using a
+\li gr::block::add_item_tag: Adds an item tag to a particular output port using a
 gr::tag_t data type.
-\li add_item_tag: Adds an item tag to a particular output port where
-each value of the tag is explicitly given.
-\li get_tags_in_range: Gets all tags from a particular input port between
-a certain range of items (in absolute item time).
-\li get_tags_in_range: Gets any tag that has a specified key from a
-particular input port between a certain range of items (in absolute
-item time).
+
+\li gr::block::add_item_tag: Adds an item tag to a particular output
+port where each value of the tag is explicitly given.
+
+\li gr::block::get_tags_in_range: Gets all tags from a particular
+input port between a certain range of items (in absolute item time).
+
+\li gr::block::get_tags_in_range: Gets any tag that has a specified
+key from a particular input port between a certain range of items (in
+absolute item time).
+
+\li gr::block::get_tags_in_window: Gets all tags from a particular
+input port between a certain range of items (in relative item time
+within the work function).
+
+\li gr::block::get_tags_in_range: Gets any tag that has a specified
+key from a particular input port between a certain range of items (in
+relative item time within the work function).
 
 
 \subsection add_item_tag Adding a Tag to a Stream
diff --git a/gnuradio-runtime/include/gnuradio/block.h b/gnuradio-runtime/include/gnuradio/block.h
index 112d251587..7390e93bc0 100644
--- a/gnuradio-runtime/include/gnuradio/block.h
+++ b/gnuradio-runtime/include/gnuradio/block.h
@@ -562,7 +562,7 @@ namespace gr {
     int set_thread_priority(int priority);
 
     bool update_rate() const;
-    
+
     // ----------------------------------------------------------------------------
 
   private:
@@ -699,6 +699,50 @@ namespace gr {
                            uint64_t abs_end,
                            const pmt::pmt_t &key);
 
+    /*!
+     * \brief Gets all tags within the relative window of the current call to work.
+     *
+     * \details
+     *
+     * This opperates much like get_tags_in_range but allows us to
+     * work within the current window of items. Item range is
+     * therefore within the possible range of 0 to
+     * ninput_items[whic_input].
+     *
+     * Range of items counts from \p rel_start to \p rel_end-1 within
+     * current window.
+     *
+     * Tags are tuples of:
+     *      (item count, source id, key, value)
+     *
+     * \param v            a vector reference to return tags into
+     * \param which_input  an integer of which input stream to pull from
+     * \param rel_start    a uint64 count of the start of the range of interest
+     * \param rel_end      a uint64 count of the end of the range of interest
+     */
+    void get_tags_in_window(std::vector<tag_t> &v,
+                            unsigned int which_input,
+                            uint64_t rel_start,
+                            uint64_t rel_end);
+
+    /*!
+     * \brief Operates like gr::block::get_tags_in_window with the
+     * ability to only return tags with the specified \p key.
+     *
+     * \details
+     *
+     * \param v            a vector reference to return tags into
+     * \param which_input  an integer of which input stream to pull from
+     * \param rel_start    a uint64 count of the start of the range of interest
+     * \param rel_end      a uint64 count of the end of the range of interest
+     * \param key          a PMT symbol key to filter only tags of this key
+     */
+    void get_tags_in_window(std::vector<tag_t> &v,
+                            unsigned int which_input,
+                            uint64_t rel_start,
+                            uint64_t rel_end,
+                            const pmt::pmt_t &key);
+
     void enable_update_rate(bool en);
 
     std::vector<long> d_max_output_buffer;
@@ -708,11 +752,11 @@ namespace gr {
      * setting/resetting of parameters thread-safe.
      *
      * Used by calling gr::thread::scoped_lock l(d_setlock);
-     */ 
+     */
     gr::thread::mutex d_setlock;
 
     /*! Used by blocks to access the logger system.
-     */ 
+     */
     gr::logger_ptr d_logger;
     gr::logger_ptr d_debug_logger;
 
diff --git a/gnuradio-runtime/lib/block.cc b/gnuradio-runtime/lib/block.cc
index 442f8dde77..169a1b0d14 100644
--- a/gnuradio-runtime/lib/block.cc
+++ b/gnuradio-runtime/lib/block.cc
@@ -288,19 +288,42 @@ namespace gr {
 
   void
   block::get_tags_in_range(std::vector<tag_t> &v,
-                           unsigned int which_output,
+                           unsigned int which_input,
                            uint64_t start, uint64_t end)
   {
-    d_detail->get_tags_in_range(v, which_output, start, end, unique_id());
+    d_detail->get_tags_in_range(v, which_input, start, end, unique_id());
   }
 
   void
   block::get_tags_in_range(std::vector<tag_t> &v,
-                           unsigned int which_output,
+                           unsigned int which_input,
                            uint64_t start, uint64_t end,
                            const pmt::pmt_t &key)
   {
-    d_detail->get_tags_in_range(v, which_output, start, end, key, unique_id());
+    d_detail->get_tags_in_range(v, which_input, start, end, key, unique_id());
+  }
+
+  void
+  block::get_tags_in_window(std::vector<tag_t> &v,
+                            unsigned int which_input,
+                            uint64_t start, uint64_t end)
+  {
+    d_detail->get_tags_in_range(v, which_input,
+                                nitems_read(which_input) + start,
+                                nitems_read(which_input) + end,
+                                unique_id());
+  }
+
+  void
+  block::get_tags_in_window(std::vector<tag_t> &v,
+                            unsigned int which_input,
+                            uint64_t start, uint64_t end,
+                            const pmt::pmt_t &key)
+  {
+    d_detail->get_tags_in_range(v, which_input,
+                                nitems_read(which_input) + start,
+                                nitems_read(which_input) + end,
+                                key, unique_id());
   }
 
   block::tag_propagation_policy_t
@@ -361,7 +384,7 @@ namespace gr {
     }
   }
 
-  int 
+  int
   block::active_thread_priority()
   {
     if(d_detail) {
@@ -370,13 +393,13 @@ namespace gr {
     return -1;
   }
 
-  int 
+  int
   block::thread_priority()
   {
     return d_priority;
   }
 
-  int 
+  int
   block::set_thread_priority(int priority)
   {
     d_priority = priority;
@@ -402,10 +425,10 @@ namespace gr {
       throw std::invalid_argument("basic_block::max_output_buffer: port out of range.");
     return d_max_output_buffer[i];
   }
-  
+
   void
   block::set_max_output_buffer(long max_output_buffer)
-  { 
+  {
     for(int i = 0; i < output_signature()->max_streams(); i++) {
       set_max_output_buffer(i, max_output_buffer);
     }
@@ -417,9 +440,9 @@ namespace gr {
     if((size_t)port >= d_max_output_buffer.size())
       d_max_output_buffer.push_back(max_output_buffer);
     else
-      d_max_output_buffer[port] = max_output_buffer; 
+      d_max_output_buffer[port] = max_output_buffer;
   }
-  
+
   long
   block::min_output_buffer(size_t i)
   {
@@ -427,7 +450,7 @@ namespace gr {
       throw std::invalid_argument("basic_block::min_output_buffer: port out of range.");
     return d_min_output_buffer[i];
   }
-  
+
   void
   block::set_min_output_buffer(long min_output_buffer)
   {
@@ -436,14 +459,14 @@ namespace gr {
       set_min_output_buffer(i, min_output_buffer);
     }
   }
-  
+
   void
   block::set_min_output_buffer(int port, long min_output_buffer)
   {
     if((size_t)port >= d_min_output_buffer.size())
       d_min_output_buffer.push_back(min_output_buffer);
     else
-      d_min_output_buffer[port] = min_output_buffer; 
+      d_min_output_buffer[port] = min_output_buffer;
   }
 
 
diff --git a/gr-blocks/include/gnuradio/blocks/message_strobe_random.h b/gr-blocks/include/gnuradio/blocks/message_strobe_random.h
index f399f637d1..8f5a20e1b3 100644
--- a/gr-blocks/include/gnuradio/blocks/message_strobe_random.h
+++ b/gr-blocks/include/gnuradio/blocks/message_strobe_random.h
@@ -43,8 +43,11 @@ namespace gr {
      * \ingroup message_tools_blk
      *
      * \details
-     * Takes a PMT message and sends it out every \p period_ms
-     * milliseconds. Useful for testing/debugging the message system.
+
+     * Takes a PMT message and sends it out every at random
+     * intervals. The interval is basedon a random distribution, \p
+     * dist, with specified mean (\p mean_ms) and variance (\p
+     * std_ms). Useful for testing/debugging the message system.
      */
     class BLOCKS_API message_strobe_random : virtual public block
     {
@@ -53,12 +56,14 @@ namespace gr {
       typedef boost::shared_ptr<message_strobe_random> sptr;
 
       /*!
-       * Make a message stobe block to send message \p msg every \p
-       * period_ms milliseconds.
+       * Make a message stobe block to sends message \p msg at random
+       * intervals defined by the distribution \p dist with mean \p
+       * mean_ms and standard deviation \p std_ms.
        *
        * \param msg The message to send as a PMT.
-       * \param period_ms the time period in milliseconds in which to
-       *                  send \p msg.
+       * \param dist The random distribution from which to draw events.
+       * \param mean_ms The mean of the distribution.
+       * \param std_ms The standard deviation of the distribution.
        */
       static sptr make(pmt::pmt_t msg, message_strobe_random_distribution_t dist, float mean_ms, float std_ms);
 
@@ -104,7 +109,7 @@ namespace gr {
        * Get the std of strobe_random.
        */
       virtual float std() const = 0;
-   
+
     };
 
   } /* namespace blocks */
diff --git a/gr-blocks/include/gnuradio/blocks/tagged_stream_to_pdu.h b/gr-blocks/include/gnuradio/blocks/tagged_stream_to_pdu.h
index 15ed50f252..af3279217e 100644
--- a/gr-blocks/include/gnuradio/blocks/tagged_stream_to_pdu.h
+++ b/gr-blocks/include/gnuradio/blocks/tagged_stream_to_pdu.h
@@ -31,11 +31,13 @@ namespace gr {
   namespace blocks {
 
     /*!
-     * \brief Turns received stream data and tags into PDUs and sends them through a message port.
+     * \brief Turns received stream data and tags into PDUs and sends
+     * them through a message port.
      * \ingroup message_tools_blk
      *
-     * The sent message is a PMT-pair (created by pmt::cons()). The first element is a dictionary
-     * containing all the tags. The second is a vector containing the actual data.
+     * The sent message is a PMT-pair (created by pmt::cons()). The
+     * first element is a dictionary containing all the tags. The
+     * second is a vector containing the actual data.
      */
     class BLOCKS_API tagged_stream_to_pdu : virtual public tagged_stream_block
     {
@@ -46,7 +48,8 @@ namespace gr {
       /*!
        * \brief Construct a tagged_stream_to_pdu block
        * \param type PDU type of pdu::vector_type
-       * \param lengthtagname The name of the tag that specifies how long the packet is.
+       * \param lengthtagname The name of the tag that specifies
+       *        how long the packet is.
        */
       static sptr make(pdu::vector_type type,
                        const std::string& lengthtagname="packet_len");
diff --git a/gr-blocks/include/gnuradio/blocks/vector_source_X.h.t b/gr-blocks/include/gnuradio/blocks/vector_source_X.h.t
index 7ff18ad083..9751514d7f 100644
--- a/gr-blocks/include/gnuradio/blocks/vector_source_X.h.t
+++ b/gr-blocks/include/gnuradio/blocks/vector_source_X.h.t
@@ -32,8 +32,19 @@ namespace gr {
   namespace blocks {
 
     /*!
-     * \brief source of @TYPE@'s that gets its data from a vector
+     * \brief Source that streams @TYPE@ items based on the input \data vector.
      * \ingroup misc_blk
+     *
+     * \details
+     * This block produces a stream of samples based on an input
+     * vector. In C++, this is a std::vector<@TYPE@>, and in Python,
+     * this is either a list or tuple. The data can repeat infinitely
+     * until the flowgraph is terminated by some other event or, the
+     * default, run the data once and stop.
+     *
+     * The vector source can also produce stream tags with the
+     * data. Pass in a vector of gr::tag_t objects and they will be
+     * emitted based on the specified offset of the tag.
      */
     class BLOCKS_API @NAME@ : virtual public sync_block
     {
author	Tom Rondeau <tom@trondeau.com>	2014-02-23 11:25:57 -0500
committer	Tom Rondeau <tom@trondeau.com>	2014-02-23 11:25:57 -0500
commit	b5fcc18523caeafebbf117cf2c838e7974856966 (patch)
tree	aac43972eb74614cded00b37d2d76c9113fa66a2
parent	77c36d3cc3bb61581621dd61aab97a9b5d1b044e (diff)