GNU Radio 3.6.4.2 C++ API
gr_buffer.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2004,2009,2010,2011 Free Software Foundation, Inc.
00004  *
00005  * This file is part of GNU Radio
00006  *
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  *
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef INCLUDED_GR_BUFFER_H
00024 #define INCLUDED_GR_BUFFER_H
00025 
00026 #include <gr_core_api.h>
00027 #include <gr_runtime_types.h>
00028 #include <boost/weak_ptr.hpp>
00029 #include <gruel/thread.h>
00030 #include <gr_tags.h>
00031 #include <deque>
00032 
00033 class gr_vmcircbuf;
00034 
00035 /*!
00036  * \brief Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
00037  *
00038  * The total size of the buffer will be rounded up to a system
00039  * dependent boundary.  This is typically the system page size, but
00040  * under MS windows is 64KB.
00041  *
00042  * \param nitems is the minimum number of items the buffer will hold.
00043  * \param sizeof_item is the size of an item in bytes.
00044  * \param link is the block that writes to this buffer.
00045  */
00046 GR_CORE_API gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link=gr_block_sptr());
00047 
00048 
00049 /*!
00050  * \brief Single writer, multiple reader fifo.
00051  * \ingroup internal
00052  */
00053 class GR_CORE_API gr_buffer {
00054  public:
00055 
00056   virtual ~gr_buffer ();
00057 
00058   /*!
00059    * \brief return number of items worth of space available for writing
00060    */
00061   int space_available ();
00062 
00063   /*!
00064    * \brief return size of this buffer in items
00065    */
00066   int bufsize() const { return d_bufsize; }
00067 
00068   /*!
00069    * \brief return pointer to write buffer.
00070    *
00071    * The return value points at space that can hold at least
00072    * space_available() items.
00073    */
00074   void *write_pointer ();
00075 
00076   /*!
00077    * \brief tell buffer that we wrote \p nitems into it
00078    */
00079   void update_write_pointer (int nitems);
00080 
00081   void set_done (bool done);
00082   bool done () const { return d_done; }
00083 
00084   /*!
00085    * \brief Return the block that writes to this buffer.
00086    */
00087   gr_block_sptr link() { return gr_block_sptr(d_link); }
00088 
00089   size_t nreaders() const { return d_readers.size(); }
00090   gr_buffer_reader* reader(size_t index) { return d_readers[index]; }
00091 
00092   gruel::mutex *mutex() { return &d_mutex; }
00093 
00094   uint64_t nitems_written() { return d_abs_write_offset; }
00095 
00096   size_t get_sizeof_item() { return d_sizeof_item; }
00097 
00098   /*!
00099    * \brief  Adds a new tag to the buffer.
00100    *
00101    * \param tag        the new tag
00102    */
00103   void add_item_tag(const gr_tag_t &tag);
00104 
00105   /*!
00106    * \brief  Removes an existing tag from the buffer.
00107    *
00108    * If no such tag is found, does nothing.
00109    *
00110    * \param tag        the tag that needs to be removed
00111    */
00112   void remove_item_tag(const gr_tag_t &tag);
00113 
00114   /*!
00115    * \brief  Removes all tags before \p max_time from buffer
00116    *
00117    * \param max_time        the time (item number) to trim up until.
00118    */
00119   void prune_tags(uint64_t max_time);
00120 
00121   std::deque<gr_tag_t>::iterator get_tags_begin() { return d_item_tags.begin(); }
00122   std::deque<gr_tag_t>::iterator get_tags_end() { return d_item_tags.end(); }
00123 
00124   // -------------------------------------------------------------------------
00125 
00126  private:
00127 
00128   friend class gr_buffer_reader;
00129   friend GR_CORE_API gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
00130   friend GR_CORE_API gr_buffer_reader_sptr gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
00131 
00132  protected:
00133   char                                 *d_base;         // base address of buffer
00134   unsigned int                          d_bufsize;      // in items
00135  private:
00136   gr_vmcircbuf                         *d_vmcircbuf;
00137   size_t                                d_sizeof_item;  // in bytes
00138   std::vector<gr_buffer_reader *>       d_readers;
00139   boost::weak_ptr<gr_block>             d_link;         // block that writes to this buffer
00140 
00141   //
00142   // The mutex protects d_write_index, d_abs_write_offset, d_done, d_item_tags
00143   // and the d_read_index's and d_abs_read_offset's in the buffer readers.
00144   //
00145   gruel::mutex                          d_mutex;
00146   unsigned int                          d_write_index;  // in items [0,d_bufsize)
00147   uint64_t                              d_abs_write_offset; // num items written since the start
00148   bool                                  d_done;
00149   std::deque<gr_tag_t>                  d_item_tags;
00150   uint64_t                              d_last_min_items_read;
00151 
00152   unsigned
00153   index_add (unsigned a, unsigned b)
00154   {
00155     unsigned s = a + b;
00156 
00157     if (s >= d_bufsize)
00158       s -= d_bufsize;
00159 
00160     assert (s < d_bufsize);
00161     return s;
00162   }
00163 
00164   unsigned
00165   index_sub (unsigned a, unsigned b)
00166   {
00167     int s = a - b;
00168 
00169     if (s < 0)
00170       s += d_bufsize;
00171 
00172     assert ((unsigned) s < d_bufsize);
00173     return s;
00174   }
00175 
00176   virtual bool allocate_buffer (int nitems, size_t sizeof_item);
00177 
00178   /*!
00179    * \brief constructor is private.  Use gr_make_buffer to create instances.
00180    *
00181    * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
00182    *
00183    * \param nitems is the minimum number of items the buffer will hold.
00184    * \param sizeof_item is the size of an item in bytes.
00185    * \param link is the block that writes to this buffer.
00186    *
00187    * The total size of the buffer will be rounded up to a system
00188    * dependent boundary.  This is typically the system page size, but
00189    * under MS windows is 64KB.
00190    */
00191   gr_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
00192 
00193   /*!
00194    * \brief disassociate \p reader from this buffer
00195    */
00196   void drop_reader (gr_buffer_reader *reader);
00197 
00198 };
00199 
00200 /*!
00201  * \brief Create a new gr_buffer_reader and attach it to buffer \p buf
00202  * \param buf is the buffer the \p gr_buffer_reader reads from.
00203  * \param nzero_preload -- number of zero items to "preload" into buffer.
00204  * \param link is the block that reads from the buffer using this gr_buffer_reader.
00205  */
00206 GR_CORE_API gr_buffer_reader_sptr
00207 gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link=gr_block_sptr());
00208 
00209 //! returns # of gr_buffers currently allocated
00210 GR_CORE_API long gr_buffer_ncurrently_allocated ();
00211 
00212 
00213 // ---------------------------------------------------------------------------
00214 
00215 /*!
00216  * \brief How we keep track of the readers of a gr_buffer.
00217  * \ingroup internal
00218  */
00219 
00220 class GR_CORE_API gr_buffer_reader {
00221  public:
00222 
00223   ~gr_buffer_reader ();
00224 
00225   /*!
00226    * \brief Return number of items available for reading.
00227    */
00228   int items_available () const;
00229 
00230   /*!
00231    * \brief Return buffer this reader reads from.
00232    */
00233   gr_buffer_sptr buffer () const { return d_buffer; }
00234 
00235 
00236   /*!
00237    * \brief Return maximum number of items that could ever be available for reading.
00238    * This is used as a sanity check in the scheduler to avoid looping forever.
00239    */
00240   int max_possible_items_available () const { return d_buffer->d_bufsize - 1; }
00241 
00242   /*!
00243    * \brief return pointer to read buffer.
00244    *
00245    * The return value points to items_available() number of items
00246    */
00247   const void *read_pointer ();
00248 
00249   /*
00250    * \brief tell buffer we read \p items from it
00251    */
00252   void update_read_pointer (int nitems);
00253 
00254   void set_done (bool done)   { d_buffer->set_done (done); }
00255   bool done () const { return d_buffer->done (); }
00256 
00257   gruel::mutex *mutex() { return d_buffer->mutex(); }
00258 
00259 
00260   uint64_t nitems_read() { return d_abs_read_offset; }
00261 
00262   size_t get_sizeof_item() { return d_buffer->get_sizeof_item(); }
00263 
00264   /*!
00265    * \brief Return the block that reads via this reader.
00266    *
00267    */
00268   gr_block_sptr link() { return gr_block_sptr(d_link); }
00269 
00270 
00271   /*!
00272    * \brief Given a [start,end), returns a vector all tags in the range.
00273    *
00274    * Get a vector of tags in given range. Range of counts is from start to end-1.
00275    *
00276    * Tags are tuples of:
00277    *      (item count, source id, key, value)
00278    *
00279    * \param v            a vector reference to return tags into
00280    * \param abs_start    a uint64 count of the start of the range of interest
00281    * \param abs_end      a uint64 count of the end of the range of interest
00282    */
00283   void get_tags_in_range(std::vector<gr_tag_t> &v,
00284                          uint64_t abs_start,
00285                          uint64_t abs_end);
00286 
00287   // -------------------------------------------------------------------------
00288 
00289  private:
00290 
00291   friend class gr_buffer;
00292   friend GR_CORE_API gr_buffer_reader_sptr
00293   gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
00294 
00295 
00296   gr_buffer_sptr                d_buffer;
00297   unsigned int                  d_read_index;   // in items [0,d->buffer.d_bufsize)
00298   uint64_t                      d_abs_read_offset;  // num items seen since the start
00299   boost::weak_ptr<gr_block>     d_link;         // block that reads via this buffer reader
00300 
00301   //! constructor is private.  Use gr_buffer::add_reader to create instances
00302   gr_buffer_reader (gr_buffer_sptr buffer, unsigned int read_index, gr_block_sptr link);
00303 };
00304 
00305 //! returns # of gr_buffer_readers currently allocated
00306 GR_CORE_API long gr_buffer_reader_ncurrently_allocated ();
00307 
00308 
00309 #endif /* INCLUDED_GR_BUFFER_H */