Moves gr_block functions dealing with tags into protected space. Adds documentation to functions in header. Adds a "srcid" parameter to the add_item_tag function.

1 files changed, 68 insertions, 15 deletions

diff --git a/gnuradio-core/src/lib/runtime/gr_block.h b/gnuradio-core/src/lib/runtime/gr_block.h
index 7564acd87..25886eb10 100644
--- a/gnuradio-core/src/lib/runtime/gr_block.h
+++ b/gnuradio-core/src/lib/runtime/gr_block.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2004,2007,2009 Free Software Foundation, Inc.
+ * Copyright 2004,2007,2009,2010 Free Software Foundation, Inc.
  * 
  * This file is part of GNU Radio
  * 
@@ -24,7 +24,7 @@
 #define INCLUDED_GR_BLOCK_H
 
 #include <gr_basic_block.h>
-#include <list>
+#include <deque>
 
 /*!
  * \brief The abstract base class for all 'terminal' processing blocks.
@@ -199,23 +199,16 @@ class gr_block : public gr_basic_block {
    */
   virtual int fixed_rate_noutput_to_ninput(int noutput);
 
-  // Return the number of items read on input stream which_input
+  /*!
+   * \brief Return the number of items read on input stream which_input
+   */
   gr_uint64 nitems_read(unsigned int which_input);
 
-  // Return the number of items written on output stream which_output
+  /*!
+   * \brief  Return the number of items written on output stream which_output
+   */
   gr_uint64 nitems_written(unsigned int which_output);
 
-  void add_item_tag(unsigned int which_output,
-		    gr_uint64 offset,
-		    const pmt::pmt_t &key, const pmt::pmt_t &value);
-
-  std::list<pmt::pmt_t> get_tags_in_range(unsigned int which_output,
-					  gr_uint64 start, gr_uint64 end);
-  
-  std::list<pmt::pmt_t> get_tags_in_range(unsigned int which_output,
-					  gr_uint64 start, gr_uint64 end,
-					  const pmt::pmt_t &key);
-
   // ----------------------------------------------------------------------------
 
  private:
@@ -234,6 +227,66 @@ class gr_block : public gr_basic_block {
 
   void set_fixed_rate(bool fixed_rate){ d_fixed_rate = fixed_rate; }
 
+  
+  /*!
+   * \brief  Adds a new tag to the deque of tags on a given buffer.
+   * 
+   * This is a call-through method to gr_block_detail to add the new tag.
+   * gr_block_detail takes care of formatting the tuple from the inputs here,
+   * it then calls gr_buffer::add_item_tag(pmt::pmt_t t), which appends the
+   * tag onto its deque of tags.
+   *
+   * \param which_ouput  an integer of which output stream to attach the tag
+   * \param abs_offset   a uint64 number of the absolute item number
+   *                     assicated with the tag. Can get from nitems_written.
+   * \param key          a PMT symbol holding the key name (i.e., a string)
+   * \param value        any PMT holding any value for the given key
+   * \param srcid        optional source ID specifier; defauls to string "NA"
+   */
+  void add_item_tag(unsigned int which_output,
+		    gr_uint64 abs_offset,
+		    const pmt::pmt_t &key,
+		    const pmt::pmt_t &value,
+		    const pmt::pmt_t &srcid=pmt::pmt_string_to_symbol("NA"));
+
+  /*!
+   * \brief Given a [start,end), returns a deque copy of all tags in the range.
+   *
+   * Pass-through function to gr_block_detail. Range of counts is from
+   * start to end-1.
+   *
+   * Tags are tuples of:
+   *      (item count, source id, key, value)
+   *
+   * \param which_input  an integer of which input stream to pull from
+   * \param abs_start    a uint64 count of the start of the range of interest
+   * \param abs_end      a uint64 count of the end of the range of interest
+   */
+  std::deque<pmt::pmt_t> get_tags_in_range(unsigned int which_input,
+					   gr_uint64 abs_start,
+					   gr_uint64 abs_end);
+  
+  /*!
+   * \brief Given a [start,end), returns a deque copy of all tags in the range
+   * with a given key.
+   *
+   * Pass-through function to gr_block_detail. Range of counts is from
+   * start to end-1.
+   *
+   * Tags are tuples of:
+   *      (item count, source id, key, value)
+   *
+   * \param which_input  an integer of which input stream to pull from
+   * \param abs_start    a uint64 count of the start of the range of interest
+   * \param abs_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
+   */
+  std::deque<pmt::pmt_t> get_tags_in_range(unsigned int which_input,
+					   gr_uint64 abs_start,
+					   gr_uint64 abs_end,
+					   const pmt::pmt_t &key);
+
+
   // These are really only for internal use, but leaving them public avoids
   // having to work up an ever-varying list of friends