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