README change

1 files changed, 309 insertions, 0 deletions

diff --git a/gnuradio-core/src/lib/runtime/gr_buffer.h b/gnuradio-core/src/lib/runtime/gr_buffer.h
new file mode 100644
index 000000000..28ea97726
--- /dev/null
+++ b/gnuradio-core/src/lib/runtime/gr_buffer.h
@@ -0,0 +1,309 @@
+/* -*- c++ -*- */
+/*
+ * Copyright 2004,2009,2010,2011 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)
+ * any later version.
+ *
+ * GNU Radio is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with GNU Radio; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#ifndef INCLUDED_GR_BUFFER_H
+#define INCLUDED_GR_BUFFER_H
+
+#include <gr_core_api.h>
+#include <gr_runtime_types.h>
+#include <boost/weak_ptr.hpp>
+#include <gruel/thread.h>
+#include <gr_tags.h>
+#include <deque>
+
+class gr_vmcircbuf;
+
+/*!
+ * \brief Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
+ *
+ * The total size of the buffer will be rounded up to a system
+ * dependent boundary.  This is typically the system page size, but
+ * under MS windows is 64KB.
+ *
+ * \param nitems is the minimum number of items the buffer will hold.
+ * \param sizeof_item is the size of an item in bytes.
+ * \param link is the block that writes to this buffer.
+ */
+GR_CORE_API gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link=gr_block_sptr());
+
+
+/*!
+ * \brief Single writer, multiple reader fifo.
+ * \ingroup internal
+ */
+class GR_CORE_API gr_buffer {
+ public:
+
+  virtual ~gr_buffer ();
+
+  /*!
+   * \brief return number of items worth of space available for writing
+   */
+  int space_available ();
+
+  /*!
+   * \brief return size of this buffer in items
+   */
+  int bufsize() const { return d_bufsize; }
+
+  /*!
+   * \brief return pointer to write buffer.
+   *
+   * The return value points at space that can hold at least
+   * space_available() items.
+   */
+  void *write_pointer ();
+
+  /*!
+   * \brief tell buffer that we wrote \p nitems into it
+   */
+  void update_write_pointer (int nitems);
+
+  void set_done (bool done);
+  bool done () const { return d_done; }
+
+  /*!
+   * \brief Return the block that writes to this buffer.
+   */
+  gr_block_sptr link() { return gr_block_sptr(d_link); }
+
+  size_t nreaders() const { return d_readers.size(); }
+  gr_buffer_reader* reader(size_t index) { return d_readers[index]; }
+
+  gruel::mutex *mutex() { return &d_mutex; }
+
+  uint64_t nitems_written() { return d_abs_write_offset; }
+
+  size_t get_sizeof_item() { return d_sizeof_item; }
+
+  /*!
+   * \brief  Adds a new tag to the buffer.
+   *
+   * \param tag        the new tag
+   */
+  void add_item_tag(const gr_tag_t &tag);
+
+  /*!
+   * \brief  Removes an existing tag from the buffer.
+   *
+   * If no such tag is found, does nothing.
+   *
+   * \param tag        the tag that needs to be removed
+   */
+  void remove_item_tag(const gr_tag_t &tag);
+
+  /*!
+   * \brief  Removes all tags before \p max_time from buffer
+   *
+   * \param max_time        the time (item number) to trim up until.
+   */
+  void prune_tags(uint64_t max_time);
+
+  std::deque<gr_tag_t>::iterator get_tags_begin() { return d_item_tags.begin(); }
+  std::deque<gr_tag_t>::iterator get_tags_end() { return d_item_tags.end(); }
+
+  // -------------------------------------------------------------------------
+
+ private:
+
+  friend class gr_buffer_reader;
+  friend GR_CORE_API gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
+  friend GR_CORE_API gr_buffer_reader_sptr gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
+
+ protected:
+  char				       *d_base;		// base address of buffer
+  unsigned int	 			d_bufsize;	// in items
+ private:
+  gr_vmcircbuf			       *d_vmcircbuf;
+  size_t	 			d_sizeof_item;	// in bytes
+  std::vector<gr_buffer_reader *>	d_readers;
+  boost::weak_ptr<gr_block>		d_link;		// block that writes to this buffer
+
+  //
+  // The mutex protects d_write_index, d_abs_write_offset, d_done, d_item_tags
+  // and the d_read_index's and d_abs_read_offset's in the buffer readers.
+  //
+  gruel::mutex				d_mutex;
+  unsigned int				d_write_index;	// in items [0,d_bufsize)
+  uint64_t                              d_abs_write_offset; // num items written since the start
+  bool					d_done;
+  std::deque<gr_tag_t>                  d_item_tags;
+  uint64_t                              d_last_min_items_read;
+
+  unsigned
+  index_add (unsigned a, unsigned b)
+  {
+    unsigned s = a + b;
+
+    if (s >= d_bufsize)
+      s -= d_bufsize;
+
+    assert (s < d_bufsize);
+    return s;
+  }
+
+  unsigned
+  index_sub (unsigned a, unsigned b)
+  {
+    int s = a - b;
+
+    if (s < 0)
+      s += d_bufsize;
+
+    assert ((unsigned) s < d_bufsize);
+    return s;
+  }
+
+  virtual bool allocate_buffer (int nitems, size_t sizeof_item);
+
+  /*!
+   * \brief constructor is private.  Use gr_make_buffer to create instances.
+   *
+   * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
+   *
+   * \param nitems is the minimum number of items the buffer will hold.
+   * \param sizeof_item is the size of an item in bytes.
+   * \param link is the block that writes to this buffer.
+   *
+   * The total size of the buffer will be rounded up to a system
+   * dependent boundary.  This is typically the system page size, but
+   * under MS windows is 64KB.
+   */
+  gr_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
+
+  /*!
+   * \brief disassociate \p reader from this buffer
+   */
+  void drop_reader (gr_buffer_reader *reader);
+
+};
+
+/*!
+ * \brief Create a new gr_buffer_reader and attach it to buffer \p buf
+ * \param buf is the buffer the \p gr_buffer_reader reads from.
+ * \param nzero_preload -- number of zero items to "preload" into buffer.
+ * \param link is the block that reads from the buffer using this gr_buffer_reader.
+ */
+GR_CORE_API gr_buffer_reader_sptr
+gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link=gr_block_sptr());
+
+//! returns # of gr_buffers currently allocated
+GR_CORE_API long gr_buffer_ncurrently_allocated ();
+
+
+// ---------------------------------------------------------------------------
+
+/*!
+ * \brief How we keep track of the readers of a gr_buffer.
+ * \ingroup internal
+ */
+
+class GR_CORE_API gr_buffer_reader {
+ public:
+
+  ~gr_buffer_reader ();
+
+  /*!
+   * \brief Return number of items available for reading.
+   */
+  int items_available () const;
+
+  /*!
+   * \brief Return buffer this reader reads from.
+   */
+  gr_buffer_sptr buffer () const { return d_buffer; }
+
+
+  /*!
+   * \brief Return maximum number of items that could ever be available for reading.
+   * This is used as a sanity check in the scheduler to avoid looping forever.
+   */
+  int max_possible_items_available () const { return d_buffer->d_bufsize - 1; }
+
+  /*!
+   * \brief return pointer to read buffer.
+   *
+   * The return value points to items_available() number of items
+   */
+  const void *read_pointer ();
+
+  /*
+   * \brief tell buffer we read \p items from it
+   */
+  void update_read_pointer (int nitems);
+
+  void set_done (bool done)   { d_buffer->set_done (done); }
+  bool done () const { return d_buffer->done (); }
+
+  gruel::mutex *mutex() { return d_buffer->mutex(); }
+
+
+  uint64_t nitems_read() { return d_abs_read_offset; }
+
+  size_t get_sizeof_item() { return d_buffer->get_sizeof_item(); }
+
+  /*!
+   * \brief Return the block that reads via this reader.
+   *
+   */
+  gr_block_sptr link() { return gr_block_sptr(d_link); }
+
+
+  /*!
+   * \brief Given a [start,end), returns a vector all tags in the range.
+   *
+   * Get a vector of tags in given range. Range of counts is from start to end-1.
+   *
+   * Tags are tuples of:
+   *      (item count, source id, key, value)
+   *
+   * \param v            a vector reference to return tags into
+   * \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
+   */
+  void get_tags_in_range(std::vector<gr_tag_t> &v,
+			 uint64_t abs_start,
+			 uint64_t abs_end);
+
+  // -------------------------------------------------------------------------
+
+ private:
+
+  friend class gr_buffer;
+  friend GR_CORE_API gr_buffer_reader_sptr
+  gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
+
+
+  gr_buffer_sptr		d_buffer;
+  unsigned int			d_read_index;	// in items [0,d->buffer.d_bufsize)
+  uint64_t                      d_abs_read_offset;  // num items seen since the start
+  boost::weak_ptr<gr_block>	d_link;		// block that reads via this buffer reader
+
+  //! constructor is private.  Use gr_buffer::add_reader to create instances
+  gr_buffer_reader (gr_buffer_sptr buffer, unsigned int read_index, gr_block_sptr link);
+};
+
+//! returns # of gr_buffer_readers currently allocated
+GR_CORE_API long gr_buffer_reader_ncurrently_allocated ();
+
+
+#endif /* INCLUDED_GR_BUFFER_H */