git.gag.com Git - debian/gnuradio/blob - gnuradio-core/src/lib/runtime/gr_buffer.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2004 Free Software Foundation, Inc.
   4  *
   5  * This file is part of GNU Radio
   6  *
   7  * GNU Radio is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 3, or (at your option)
  10  * any later version.
  11  *
  12  * GNU Radio is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with GNU Radio; see the file COPYING.  If not, write to
  19  * the Free Software Foundation, Inc., 51 Franklin Street,
  20  * Boston, MA 02110-1301, USA.
  21  */
  22
  23 #ifndef INCLUDED_GR_BUFFER_H
  24 #define INCLUDED_GR_BUFFER_H
  25
  26 #include <gr_runtime_types.h>
  27 #include <boost/weak_ptr.hpp>
  28 #include <boost/thread.hpp>
  29
  30 class gr_vmcircbuf;
  31
  32 /*!
  33  * \brief Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
  34  *
  35  * The total size of the buffer will be rounded up to a system
  36  * dependent boundary.  This is typically the system page size, but
  37  * under MS windows is 64KB.
  38  *
  39  * \param nitems is the minimum number of items the buffer will hold.
  40  * \param sizeof_item is the size of an item in bytes.
  41  * \param link is the block that writes to this buffer.
  42  */
  43 gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link=gr_block_sptr());
  44
  45
  46 /*!
  47  * \brief Single writer, multiple reader fifo.
  48  * \ingroup internal
  49  */
  50 class gr_buffer {
  51  public:
  52
  53   typedef boost::unique_lock<boost::mutex>  scoped_lock;
  54
  55   virtual ~gr_buffer ();
  56
  57   /*!
  58    * \brief return number of items worth of space available for writing
  59    */
  60   int space_available ();
  61
  62   /*!
  63    * \brief return size of this buffer in items
  64    */
  65   int bufsize() const { return d_bufsize; }
  66
  67   /*!
  68    * \brief return pointer to write buffer.
  69    *
  70    * The return value points at space that can hold at least
  71    * space_available() items.
  72    */
  73   void *write_pointer ();
  74
  75   /*!
  76    * \brief tell buffer that we wrote \p nitems into it
  77    */
  78   void update_write_pointer (int nitems);
  79
  80   void set_done (bool done);
  81   bool done () const { return d_done; }
  82
  83   /*!
  84    * \brief Return the block that writes to this buffer.
  85    */
  86   gr_block_sptr link() { return gr_block_sptr(d_link); }
  87
  88   size_t nreaders() const { return d_readers.size(); }
  89   gr_buffer_reader* reader(size_t index) { return d_readers[index]; }
  90
  91   boost::mutex *mutex() { return &d_mutex; }
  92
  93   // -------------------------------------------------------------------------
  94
  95  private:
  96
  97   friend class gr_buffer_reader;
  98   friend gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
  99   friend gr_buffer_reader_sptr gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
 100
 101  protected:
 102   char                                 *d_base;         // base address of buffer
 103   unsigned int                          d_bufsize;      // in items
 104  private:
 105   gr_vmcircbuf                         *d_vmcircbuf;
 106   size_t                                d_sizeof_item;  // in bytes
 107   std::vector<gr_buffer_reader *>       d_readers;
 108   boost::weak_ptr<gr_block>             d_link;         // block that writes to this buffer
 109
 110   //
 111   // The mutex protects d_write_index, d_done and the d_read_index's in the buffer readers.
 112   //
 113   boost::mutex                          d_mutex;
 114   unsigned int                          d_write_index;  // in items [0,d_bufsize)
 115   bool                                  d_done;
 116
 117   unsigned
 118   index_add (unsigned a, unsigned b)
 119   {
 120     unsigned s = a + b;
 121
 122     if (s >= d_bufsize)
 123       s -= d_bufsize;
 124
 125     assert (s < d_bufsize);
 126     return s;
 127   }
 128
 129   unsigned
 130   index_sub (unsigned a, unsigned b)
 131   {
 132     int s = a - b;
 133
 134     if (s < 0)
 135       s += d_bufsize;
 136
 137     assert ((unsigned) s < d_bufsize);
 138     return s;
 139   }
 140
 141   virtual bool allocate_buffer (int nitems, size_t sizeof_item);
 142
 143   /*!
 144    * \brief constructor is private.  Use gr_make_buffer to create instances.
 145    *
 146    * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
 147    *
 148    * \param nitems is the minimum number of items the buffer will hold.
 149    * \param sizeof_item is the size of an item in bytes.
 150    * \param link is the block that writes to this buffer.
 151    *
 152    * The total size of the buffer will be rounded up to a system
 153    * dependent boundary.  This is typically the system page size, but
 154    * under MS windows is 64KB.
 155    */
 156   gr_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
 157
 158   /*!
 159    * \brief disassociate \p reader from this buffer
 160    */
 161   void drop_reader (gr_buffer_reader *reader);
 162
 163 };
 164
 165 /*!
 166  * \brief Create a new gr_buffer_reader and attach it to buffer \p buf
 167  * \param buf is the buffer the \p gr_buffer_reader reads from.
 168  * \param nzero_preload -- number of zero items to "preload" into buffer.
 169  * \param link is the block that reads from the buffer using this gr_buffer_reader.
 170  */
 171 gr_buffer_reader_sptr
 172 gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link=gr_block_sptr());
 173
 174 //! returns # of gr_buffers currently allocated
 175 long gr_buffer_ncurrently_allocated ();
 176
 177
 178 // ---------------------------------------------------------------------------
 179
 180 /*!
 181  * \brief How we keep track of the readers of a gr_buffer.
 182  * \ingroup internal
 183  */
 184
 185 class gr_buffer_reader {
 186  public:
 187
 188   typedef gr_buffer::scoped_lock scoped_lock;
 189
 190   ~gr_buffer_reader ();
 191
 192   /*!
 193    * \brief Return number of items available for reading.
 194    */
 195   int items_available () const;
 196
 197   /*!
 198    * \brief Return buffer this reader reads from.
 199    */
 200   gr_buffer_sptr buffer () const { return d_buffer; }
 201
 202
 203   /*!
 204    * \brief Return maximum number of items that could ever be available for reading.
 205    * This is used as a sanity check in the scheduler to avoid looping forever.
 206    */
 207   int max_possible_items_available () const { return d_buffer->d_bufsize - 1; }
 208
 209   /*!
 210    * \brief return pointer to read buffer.
 211    *
 212    * The return value points to items_available() number of items
 213    */
 214   const void *read_pointer ();
 215
 216   /*
 217    * \brief tell buffer we read \p items from it
 218    */
 219   void update_read_pointer (int nitems);
 220
 221   void set_done (bool done)   { d_buffer->set_done (done); }
 222   bool done () const { return d_buffer->done (); }
 223
 224   boost::mutex *mutex() { return d_buffer->mutex(); }
 225
 226
 227   /*!
 228    * \brief Return the block that reads via this reader.
 229    */
 230   gr_block_sptr link() { return gr_block_sptr(d_link); }
 231
 232   // -------------------------------------------------------------------------
 233
 234  private:
 235
 236   friend class gr_buffer;
 237   friend gr_buffer_reader_sptr
 238   gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
 239
 240
 241   gr_buffer_sptr                d_buffer;
 242   unsigned int                  d_read_index;   // in items [0,d->buffer.d_bufsize)
 243   boost::weak_ptr<gr_block>     d_link;         // block that reads via this buffer reader
 244
 245   //! constructor is private.  Use gr_buffer::add_reader to create instances
 246   gr_buffer_reader (gr_buffer_sptr buffer, unsigned int read_index, gr_block_sptr link);
 247 };
 248
 249 //! returns # of gr_buffer_readers currently allocated
 250 long gr_buffer_reader_ncurrently_allocated ();
 251
 252
 253 #endif /* INCLUDED_GR_BUFFER_H */