GNU Radio 3.4.0 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_runtime_types.h>
00027 #include <boost/weak_ptr.hpp>
00028 #include <gruel/thread.h>
00029 #include <gruel/pmt.h>
00030 #include <deque>
00031 
00032 class gr_vmcircbuf;
00033 
00034 /*!
00035  * \brief Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
00036  *
00037  * The total size of the buffer will be rounded up to a system
00038  * dependent boundary.  This is typically the system page size, but
00039  * under MS windows is 64KB.
00040  *
00041  * \param nitems is the minimum number of items the buffer will hold.
00042  * \param sizeof_item is the size of an item in bytes.
00043  * \param link is the block that writes to this buffer.
00044  */
00045 gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link=gr_block_sptr());
00046 
00047 
00048 /*!
00049  * \brief Single writer, multiple reader fifo.
00050  * \ingroup internal
00051  */
00052 class gr_buffer {
00053  public:
00054 
00055   virtual ~gr_buffer ();
00056 
00057   /*!
00058    * \brief return number of items worth of space available for writing
00059    */
00060   int space_available ();
00061 
00062   /*!
00063    * \brief return size of this buffer in items
00064    */
00065   int bufsize() const { return d_bufsize; }
00066 
00067   /*!
00068    * \brief return pointer to write buffer.
00069    *
00070    * The return value points at space that can hold at least
00071    * space_available() items.
00072    */
00073   void *write_pointer ();
00074 
00075   /*!
00076    * \brief tell buffer that we wrote \p nitems into it
00077    */
00078   void update_write_pointer (int nitems);
00079 
00080   void set_done (bool done);
00081   bool done () const { return d_done; }
00082 
00083   /*!
00084    * \brief Return the block that writes to this buffer.
00085    */
00086   gr_block_sptr link() { return gr_block_sptr(d_link); }
00087 
00088   size_t nreaders() const { return d_readers.size(); }
00089   gr_buffer_reader* reader(size_t index) { return d_readers[index]; }
00090 
00091   gruel::mutex *mutex() { return &d_mutex; }
00092 
00093   uint64_t nitems_written() { return d_abs_write_offset; }
00094 
00095 
00096   /*!
00097    * \brief  Adds a new tag to the buffer.
00098    * 
00099    * \param tag        a PMT tuple containing the new tag
00100    */
00101   void add_item_tag(const pmt::pmt_t &tag);
00102 
00103   /*!
00104    * \brief  Removes all tags before \p max_time from buffer
00105    * 
00106    * \param max_time        the time (item number) to trim up until.
00107    */
00108   void prune_tags(uint64_t max_time);
00109 
00110   std::deque<pmt::pmt_t>::iterator get_tags_begin() { return d_item_tags.begin(); }
00111   std::deque<pmt::pmt_t>::iterator get_tags_end() { return d_item_tags.end(); }
00112 
00113   // -------------------------------------------------------------------------
00114 
00115  private:
00116 
00117   friend class gr_buffer_reader;
00118   friend gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
00119   friend gr_buffer_reader_sptr gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
00120 
00121  protected:
00122   char                                 *d_base;         // base address of buffer
00123   unsigned int                          d_bufsize;      // in items
00124  private:
00125   gr_vmcircbuf                         *d_vmcircbuf;
00126   size_t                                d_sizeof_item;  // in bytes
00127   std::vector<gr_buffer_reader *>       d_readers;
00128   boost::weak_ptr<gr_block>             d_link;         // block that writes to this buffer
00129 
00130   //
00131   // The mutex protects d_write_index, d_abs_write_offset, d_done, d_item_tags 
00132   // and the d_read_index's and d_abs_read_offset's in the buffer readers.
00133   //
00134   gruel::mutex                          d_mutex;
00135   unsigned int                          d_write_index;  // in items [0,d_bufsize)
00136   uint64_t                              d_abs_write_offset; // num items written since the start
00137   bool                                  d_done;
00138   std::deque<pmt::pmt_t>                d_item_tags;
00139   uint64_t                              d_last_min_items_read;
00140   
00141   unsigned
00142   index_add (unsigned a, unsigned b)
00143   {
00144     unsigned s = a + b;
00145 
00146     if (s >= d_bufsize)
00147       s -= d_bufsize;
00148 
00149     assert (s < d_bufsize);
00150     return s;
00151   }
00152 
00153   unsigned
00154   index_sub (unsigned a, unsigned b)
00155   {
00156     int s = a - b;
00157 
00158     if (s < 0)
00159       s += d_bufsize;
00160 
00161     assert ((unsigned) s < d_bufsize);
00162     return s;
00163   }
00164 
00165   virtual bool allocate_buffer (int nitems, size_t sizeof_item);
00166 
00167   /*!
00168    * \brief constructor is private.  Use gr_make_buffer to create instances.
00169    *
00170    * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
00171    *
00172    * \param nitems is the minimum number of items the buffer will hold.
00173    * \param sizeof_item is the size of an item in bytes.
00174    * \param link is the block that writes to this buffer.
00175    *
00176    * The total size of the buffer will be rounded up to a system
00177    * dependent boundary.  This is typically the system page size, but
00178    * under MS windows is 64KB.
00179    */
00180   gr_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
00181 
00182   /*!
00183    * \brief disassociate \p reader from this buffer
00184    */
00185   void drop_reader (gr_buffer_reader *reader);
00186 
00187 };
00188 
00189 /*!
00190  * \brief Create a new gr_buffer_reader and attach it to buffer \p buf
00191  * \param buf is the buffer the \p gr_buffer_reader reads from.
00192  * \param nzero_preload -- number of zero items to "preload" into buffer.
00193  * \param link is the block that reads from the buffer using this gr_buffer_reader.
00194  */
00195 gr_buffer_reader_sptr 
00196 gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link=gr_block_sptr());
00197 
00198 //! returns # of gr_buffers currently allocated
00199 long gr_buffer_ncurrently_allocated ();
00200 
00201 
00202 // ---------------------------------------------------------------------------
00203 
00204 /*!
00205  * \brief How we keep track of the readers of a gr_buffer.
00206  * \ingroup internal
00207  */
00208 
00209 class gr_buffer_reader {
00210  public:
00211 
00212   ~gr_buffer_reader ();
00213 
00214   /*!
00215    * \brief Return number of items available for reading.
00216    */
00217   int items_available () const;
00218 
00219   /*!
00220    * \brief Return buffer this reader reads from.
00221    */
00222   gr_buffer_sptr buffer () const { return d_buffer; }
00223 
00224 
00225   /*!
00226    * \brief Return maximum number of items that could ever be available for reading.
00227    * This is used as a sanity check in the scheduler to avoid looping forever.
00228    */
00229   int max_possible_items_available () const { return d_buffer->d_bufsize - 1; }
00230 
00231   /*!
00232    * \brief return pointer to read buffer.
00233    *
00234    * The return value points to items_available() number of items
00235    */
00236   const void *read_pointer ();
00237 
00238   /*
00239    * \brief tell buffer we read \p items from it
00240    */
00241   void update_read_pointer (int nitems);
00242 
00243   void set_done (bool done)   { d_buffer->set_done (done); }
00244   bool done () const { return d_buffer->done (); }
00245 
00246   gruel::mutex *mutex() { return d_buffer->mutex(); }
00247 
00248 
00249   uint64_t nitems_read() { return d_abs_read_offset; }
00250 
00251   /*!
00252    * \brief Return the block that reads via this reader.
00253    *
00254    */
00255   gr_block_sptr link() { return gr_block_sptr(d_link); }
00256 
00257 
00258   /*!
00259    * \brief Given a [start,end), returns a vector all tags in the range.
00260    *
00261    * Get a vector of tags in given range. Range of counts is from start to end-1.
00262    *
00263    * Tags are tuples of:
00264    *      (item count, source id, key, value)
00265    *
00266    * \param v            a vector reference to return tags into
00267    * \param abs_start    a uint64 count of the start of the range of interest
00268    * \param abs_end      a uint64 count of the end of the range of interest
00269    */
00270   void get_tags_in_range(std::vector<pmt::pmt_t> &v,
00271                          uint64_t abs_start,
00272                          uint64_t abs_end);
00273 
00274   // -------------------------------------------------------------------------
00275 
00276  private:
00277 
00278   friend class gr_buffer;
00279   friend gr_buffer_reader_sptr 
00280   gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
00281 
00282 
00283   gr_buffer_sptr                d_buffer;
00284   unsigned int                  d_read_index;   // in items [0,d->buffer.d_bufsize)
00285   uint64_t                      d_abs_read_offset;  // num items seen since the start
00286   boost::weak_ptr<gr_block>     d_link;         // block that reads via this buffer reader
00287 
00288   //! constructor is private.  Use gr_buffer::add_reader to create instances
00289   gr_buffer_reader (gr_buffer_sptr buffer, unsigned int read_index, gr_block_sptr link);
00290 };
00291 
00292 //! returns # of gr_buffer_readers currently allocated
00293 long gr_buffer_reader_ncurrently_allocated ();
00294 
00295 
00296 #endif /* INCLUDED_GR_BUFFER_H */