GNU Radio 3.2.2 C++ API
|
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 */