GNU Radio 3.2.2 C++ API

gr_buffer.h

Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2004 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 <boost/thread.hpp>
00029 
00030 class gr_vmcircbuf;
00031 
00032 /*!
00033  * \brief Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
00034  *
00035  * The total size of the buffer will be rounded up to a system
00036  * dependent boundary.  This is typically the system page size, but
00037  * under MS windows is 64KB.
00038  *
00039  * \param nitems is the minimum number of items the buffer will hold.
00040  * \param sizeof_item is the size of an item in bytes.
00041  * \param link is the block that writes to this buffer.
00042  */
00043 gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link=gr_block_sptr());
00044 
00045 
00046 /*!
00047  * \brief Single writer, multiple reader fifo.
00048  * \ingroup internal
00049  */
00050 class gr_buffer {
00051  public:
00052 
00053   typedef boost::unique_lock<boost::mutex>  scoped_lock;
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   boost::mutex *mutex() { return &d_mutex; }
00092 
00093   // -------------------------------------------------------------------------
00094 
00095  private:
00096 
00097   friend class gr_buffer_reader;
00098   friend gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
00099   friend gr_buffer_reader_sptr gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
00100 
00101  protected:
00102   char                                 *d_base;         // base address of buffer
00103   unsigned int                          d_bufsize;      // in items
00104  private:
00105   gr_vmcircbuf                         *d_vmcircbuf;
00106   size_t                                d_sizeof_item;  // in bytes
00107   std::vector<gr_buffer_reader *>       d_readers;
00108   boost::weak_ptr<gr_block>             d_link;         // block that writes to this buffer
00109 
00110   //
00111   // The mutex protects d_write_index, d_done and the d_read_index's in the buffer readers.
00112   //
00113   boost::mutex                          d_mutex;
00114   unsigned int                          d_write_index;  // in items [0,d_bufsize)
00115   bool                                  d_done;
00116   
00117   unsigned
00118   index_add (unsigned a, unsigned b)
00119   {
00120     unsigned s = a + b;
00121 
00122     if (s >= d_bufsize)
00123       s -= d_bufsize;
00124 
00125     assert (s < d_bufsize);
00126     return s;
00127   }
00128 
00129   unsigned
00130   index_sub (unsigned a, unsigned b)
00131   {
00132     int s = a - b;
00133 
00134     if (s < 0)
00135       s += d_bufsize;
00136 
00137     assert ((unsigned) s < d_bufsize);
00138     return s;
00139   }
00140 
00141   virtual bool allocate_buffer (int nitems, size_t sizeof_item);
00142 
00143   /*!
00144    * \brief constructor is private.  Use gr_make_buffer to create instances.
00145    *
00146    * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
00147    *
00148    * \param nitems is the minimum number of items the buffer will hold.
00149    * \param sizeof_item is the size of an item in bytes.
00150    * \param link is the block that writes to this buffer.
00151    *
00152    * The total size of the buffer will be rounded up to a system
00153    * dependent boundary.  This is typically the system page size, but
00154    * under MS windows is 64KB.
00155    */
00156   gr_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
00157 
00158   /*!
00159    * \brief disassociate \p reader from this buffer
00160    */
00161   void drop_reader (gr_buffer_reader *reader);
00162 
00163 };
00164 
00165 /*!
00166  * \brief Create a new gr_buffer_reader and attach it to buffer \p buf
00167  * \param buf is the buffer the \p gr_buffer_reader reads from.
00168  * \param nzero_preload -- number of zero items to "preload" into buffer.
00169  * \param link is the block that reads from the buffer using this gr_buffer_reader.
00170  */
00171 gr_buffer_reader_sptr 
00172 gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link=gr_block_sptr());
00173 
00174 //! returns # of gr_buffers currently allocated
00175 long gr_buffer_ncurrently_allocated ();
00176 
00177 
00178 // ---------------------------------------------------------------------------
00179 
00180 /*!
00181  * \brief How we keep track of the readers of a gr_buffer.
00182  * \ingroup internal
00183  */
00184 
00185 class gr_buffer_reader {
00186  public:
00187 
00188   typedef gr_buffer::scoped_lock scoped_lock;
00189 
00190   ~gr_buffer_reader ();
00191 
00192   /*!
00193    * \brief Return number of items available for reading.
00194    */
00195   int items_available () const;
00196 
00197   /*!
00198    * \brief Return buffer this reader reads from.
00199    */
00200   gr_buffer_sptr buffer () const { return d_buffer; }
00201 
00202 
00203   /*!
00204    * \brief Return maximum number of items that could ever be available for reading.
00205    * This is used as a sanity check in the scheduler to avoid looping forever.
00206    */
00207   int max_possible_items_available () const { return d_buffer->d_bufsize - 1; }
00208 
00209   /*!
00210    * \brief return pointer to read buffer.
00211    *
00212    * The return value points to items_available() number of items
00213    */
00214   const void *read_pointer ();
00215 
00216   /*
00217    * \brief tell buffer we read \p items from it
00218    */
00219   void update_read_pointer (int nitems);
00220 
00221   void set_done (bool done)   { d_buffer->set_done (done); }
00222   bool done () const { return d_buffer->done (); }
00223 
00224   boost::mutex *mutex() { return d_buffer->mutex(); }
00225 
00226 
00227   /*!
00228    * \brief Return the block that reads via this reader.
00229    */
00230   gr_block_sptr link() { return gr_block_sptr(d_link); }
00231 
00232   // -------------------------------------------------------------------------
00233 
00234  private:
00235 
00236   friend class gr_buffer;
00237   friend gr_buffer_reader_sptr 
00238   gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
00239 
00240 
00241   gr_buffer_sptr                d_buffer;
00242   unsigned int                  d_read_index;   // in items [0,d->buffer.d_bufsize)
00243   boost::weak_ptr<gr_block>     d_link;         // block that reads via this buffer reader
00244 
00245   //! constructor is private.  Use gr_buffer::add_reader to create instances
00246   gr_buffer_reader (gr_buffer_sptr buffer, unsigned int read_index, gr_block_sptr link);
00247 };
00248 
00249 //! returns # of gr_buffer_readers currently allocated
00250 long gr_buffer_reader_ncurrently_allocated ();
00251 
00252 
00253 #endif /* INCLUDED_GR_BUFFER_H */