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

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2004,2009 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 <gruel/thread.h>
  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   virtual ~gr_buffer ();
  54
  55   /*!
  56    * \brief return number of items worth of space available for writing
  57    */
  58   int space_available ();
  59
  60   /*!
  61    * \brief return size of this buffer in items
  62    */
  63   int bufsize() const { return d_bufsize; }
  64
  65   /*!
  66    * \brief return pointer to write buffer.
  67    *
  68    * The return value points at space that can hold at least
  69    * space_available() items.
  70    */
  71   void *write_pointer ();
  72
  73   /*!
  74    * \brief tell buffer that we wrote \p nitems into it
  75    */
  76   void update_write_pointer (int nitems);
  77
  78   void set_done (bool done);
  79   bool done () const { return d_done; }
  80
  81   /*!
  82    * \brief Return the block that writes to this buffer.
  83    */
  84   gr_block_sptr link() { return gr_block_sptr(d_link); }
  85
  86   size_t nreaders() const { return d_readers.size(); }
  87   gr_buffer_reader* reader(size_t index) { return d_readers[index]; }
  88
  89   gruel::mutex *mutex() { return &d_mutex; }
  90
  91   // -------------------------------------------------------------------------
  92
  93  private:
  94
  95   friend class gr_buffer_reader;
  96   friend gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
  97   friend gr_buffer_reader_sptr gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
  98
  99  protected:
 100   char                                 *d_base;         // base address of buffer
 101   unsigned int                          d_bufsize;      // in items
 102  private:
 103   gr_vmcircbuf                         *d_vmcircbuf;
 104   size_t                                d_sizeof_item;  // in bytes
 105   std::vector<gr_buffer_reader *>       d_readers;
 106   boost::weak_ptr<gr_block>             d_link;         // block that writes to this buffer
 107
 108   //
 109   // The mutex protects d_write_index, d_done and the d_read_index's in the buffer readers.
 110   //
 111   gruel::mutex                          d_mutex;
 112   unsigned int                          d_write_index;  // in items [0,d_bufsize)
 113   bool                                  d_done;
 114
 115   unsigned
 116   index_add (unsigned a, unsigned b)
 117   {
 118     unsigned s = a + b;
 119
 120     if (s >= d_bufsize)
 121       s -= d_bufsize;
 122
 123     assert (s < d_bufsize);
 124     return s;
 125   }
 126
 127   unsigned
 128   index_sub (unsigned a, unsigned b)
 129   {
 130     int s = a - b;
 131
 132     if (s < 0)
 133       s += d_bufsize;
 134
 135     assert ((unsigned) s < d_bufsize);
 136     return s;
 137   }
 138
 139   virtual bool allocate_buffer (int nitems, size_t sizeof_item);
 140
 141   /*!
 142    * \brief constructor is private.  Use gr_make_buffer to create instances.
 143    *
 144    * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
 145    *
 146    * \param nitems is the minimum number of items the buffer will hold.
 147    * \param sizeof_item is the size of an item in bytes.
 148    * \param link is the block that writes to this buffer.
 149    *
 150    * The total size of the buffer will be rounded up to a system
 151    * dependent boundary.  This is typically the system page size, but
 152    * under MS windows is 64KB.
 153    */
 154   gr_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
 155
 156   /*!
 157    * \brief disassociate \p reader from this buffer
 158    */
 159   void drop_reader (gr_buffer_reader *reader);
 160
 161 };
 162
 163 /*!
 164  * \brief Create a new gr_buffer_reader and attach it to buffer \p buf
 165  * \param buf is the buffer the \p gr_buffer_reader reads from.
 166  * \param nzero_preload -- number of zero items to "preload" into buffer.
 167  * \param link is the block that reads from the buffer using this gr_buffer_reader.
 168  */
 169 gr_buffer_reader_sptr
 170 gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link=gr_block_sptr());
 171
 172 //! returns # of gr_buffers currently allocated
 173 long gr_buffer_ncurrently_allocated ();
 174
 175
 176 // ---------------------------------------------------------------------------
 177
 178 /*!
 179  * \brief How we keep track of the readers of a gr_buffer.
 180  * \ingroup internal
 181  */
 182
 183 class gr_buffer_reader {
 184  public:
 185
 186   ~gr_buffer_reader ();
 187
 188   /*!
 189    * \brief Return number of items available for reading.
 190    */
 191   int items_available () const;
 192
 193   /*!
 194    * \brief Return buffer this reader reads from.
 195    */
 196   gr_buffer_sptr buffer () const { return d_buffer; }
 197
 198
 199   /*!
 200    * \brief Return maximum number of items that could ever be available for reading.
 201    * This is used as a sanity check in the scheduler to avoid looping forever.
 202    */
 203   int max_possible_items_available () const { return d_buffer->d_bufsize - 1; }
 204
 205   /*!
 206    * \brief return pointer to read buffer.
 207    *
 208    * The return value points to items_available() number of items
 209    */
 210   const void *read_pointer ();
 211
 212   /*
 213    * \brief tell buffer we read \p items from it
 214    */
 215   void update_read_pointer (int nitems);
 216
 217   void set_done (bool done)   { d_buffer->set_done (done); }
 218   bool done () const { return d_buffer->done (); }
 219
 220   gruel::mutex *mutex() { return d_buffer->mutex(); }
 221
 222
 223   /*!
 224    * \brief Return the block that reads via this reader.
 225    */
 226   gr_block_sptr link() { return gr_block_sptr(d_link); }
 227
 228   // -------------------------------------------------------------------------
 229
 230  private:
 231
 232   friend class gr_buffer;
 233   friend gr_buffer_reader_sptr
 234   gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
 235
 236
 237   gr_buffer_sptr                d_buffer;
 238   unsigned int                  d_read_index;   // in items [0,d->buffer.d_bufsize)
 239   boost::weak_ptr<gr_block>     d_link;         // block that reads via this buffer reader
 240
 241   //! constructor is private.  Use gr_buffer::add_reader to create instances
 242   gr_buffer_reader (gr_buffer_sptr buffer, unsigned int read_index, gr_block_sptr link);
 243 };
 244
 245 //! returns # of gr_buffer_readers currently allocated
 246 long gr_buffer_reader_ncurrently_allocated ();
 247
 248
 249 #endif /* INCLUDED_GR_BUFFER_H */