GNU Radio Manual and C++ API Reference  3.7.4
The Free & Open Software Radio Ecosystem
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
buffer.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2004,2009-2011,2013 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_RUNTIME_BUFFER_H
24 #define INCLUDED_GR_RUNTIME_BUFFER_H
25 
26 #include <gnuradio/api.h>
27 #include <gnuradio/runtime_types.h>
28 #include <gnuradio/tags.h>
29 #include <boost/weak_ptr.hpp>
30 #include <gnuradio/thread/thread.h>
31 #include <deque>
32 
33 namespace gr {
34 
35  class vmcircbuf;
36 
37  /*!
38  * \brief Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
39  *
40  * The total size of the buffer will be rounded up to a system
41  * dependent boundary. This is typically the system page size, but
42  * under MS windows is 64KB.
43  *
44  * \param nitems is the minimum number of items the buffer will hold.
45  * \param sizeof_item is the size of an item in bytes.
46  * \param link is the block that writes to this buffer.
47  */
48  GR_RUNTIME_API buffer_sptr make_buffer(int nitems, size_t sizeof_item,
49  block_sptr link=block_sptr());
50 
51  /*!
52  * \brief Single writer, multiple reader fifo.
53  * \ingroup internal
54  */
56  {
57  public:
58  virtual ~buffer();
59 
60  /*!
61  * \brief return number of items worth of space available for writing
62  */
63  int space_available();
64 
65  /*!
66  * \brief return size of this buffer in items
67  */
68  int bufsize() const { return d_bufsize; }
69 
70  /*!
71  * \brief return pointer to write buffer.
72  *
73  * The return value points at space that can hold at least
74  * space_available() items.
75  */
76  void *write_pointer();
77 
78  /*!
79  * \brief tell buffer that we wrote \p nitems into it
80  */
81  void update_write_pointer(int nitems);
82 
83  void set_done(bool done);
84  bool done() const { return d_done; }
85 
86  /*!
87  * \brief Return the block that writes to this buffer.
88  */
89  block_sptr link() { return block_sptr(d_link); }
90 
91  size_t nreaders() const { return d_readers.size(); }
92  buffer_reader* reader(size_t index) { return d_readers[index]; }
93 
94  gr::thread::mutex *mutex() { return &d_mutex; }
95 
96  uint64_t nitems_written() { return d_abs_write_offset; }
97 
98  size_t get_sizeof_item() { return d_sizeof_item; }
99 
100  /*!
101  * \brief Adds a new tag to the buffer.
102  *
103  * \param tag the new tag
104  */
105  void add_item_tag(const tag_t &tag);
106 
107  /*!
108  * \brief Removes an existing tag from the buffer.
109  *
110  * If no such tag is found, does nothing.
111  * Note: Doesn't actually physically delete the tag, but
112  * marks it as deleted. For the user, this has the same effect:
113  * Any subsequent calls to get_tags_in_range() will not return
114  * the tag.
115  *
116  * \param tag the tag that needs to be removed
117  * \param id the unique ID of the block calling this function
118  */
119  void remove_item_tag(const tag_t &tag, long id);
120 
121  /*!
122  * \brief Removes all tags before \p max_time from buffer
123  *
124  * \param max_time the time (item number) to trim up until.
125  */
126  void prune_tags(uint64_t max_time);
127 
128  std::deque<tag_t>::iterator get_tags_begin() { return d_item_tags.begin(); }
129  std::deque<tag_t>::iterator get_tags_end() { return d_item_tags.end(); }
130 
131  // -------------------------------------------------------------------------
132 
133  private:
134  friend class buffer_reader;
135  friend GR_RUNTIME_API buffer_sptr make_buffer(int nitems, size_t sizeof_item, block_sptr link);
137  (buffer_sptr buf, int nzero_preload, block_sptr link, int delay);
138 
139  protected:
140  char *d_base; // base address of buffer
141  unsigned int d_bufsize; // in items
142 
143  // Keep track of maximum sample delay of any reader; Only prune tags past this.
145 
146  private:
147  gr::vmcircbuf *d_vmcircbuf;
148  size_t d_sizeof_item; // in bytes
149  std::vector<buffer_reader *> d_readers;
150  boost::weak_ptr<block> d_link; // block that writes to this buffer
151 
152  //
153  // The mutex protects d_write_index, d_abs_write_offset, d_done, d_item_tags
154  // and the d_read_index's and d_abs_read_offset's in the buffer readers.
155  //
156  gr::thread::mutex d_mutex;
157  unsigned int d_write_index; // in items [0,d_bufsize)
158  uint64_t d_abs_write_offset; // num items written since the start
159  bool d_done;
160  std::deque<tag_t> d_item_tags;
161  uint64_t d_last_min_items_read;
162 
163  unsigned index_add(unsigned a, unsigned b)
164  {
165  unsigned s = a + b;
166 
167  if(s >= d_bufsize)
168  s -= d_bufsize;
169 
170  assert(s < d_bufsize);
171  return s;
172  }
173 
174  unsigned index_sub(unsigned a, unsigned b)
175  {
176  int s = a - b;
177 
178  if(s < 0)
179  s += d_bufsize;
180 
181  assert((unsigned) s < d_bufsize);
182  return s;
183  }
184 
185  virtual bool allocate_buffer(int nitems, size_t sizeof_item);
186 
187  /*!
188  * \brief constructor is private. Use gr_make_buffer to create instances.
189  *
190  * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
191  *
192  * \param nitems is the minimum number of items the buffer will hold.
193  * \param sizeof_item is the size of an item in bytes.
194  * \param link is the block that writes to this buffer.
195  *
196  * The total size of the buffer will be rounded up to a system
197  * dependent boundary. This is typically the system page size, but
198  * under MS windows is 64KB.
199  */
200  buffer(int nitems, size_t sizeof_item, block_sptr link);
201 
202  /*!
203  * \brief disassociate \p reader from this buffer
204  */
205  void drop_reader(buffer_reader *reader);
206  };
207 
208  /*!
209  * \brief Create a new gr::buffer_reader and attach it to buffer \p buf
210  * \param buf is the buffer the \p gr::buffer_reader reads from.
211  * \param nzero_preload -- number of zero items to "preload" into buffer.
212  * \param link is the block that reads from the buffer using this gr::buffer_reader.
213  * \param delay Optional setting to declare the buffer's sample delay.
214  */
215  GR_RUNTIME_API buffer_reader_sptr
216  buffer_add_reader(buffer_sptr buf, int nzero_preload, block_sptr link=block_sptr(), int delay=0);
217 
218  //! returns # of buffers currently allocated
220 
221 
222  // ---------------------------------------------------------------------------
223 
224  /*!
225  * \brief How we keep track of the readers of a gr::buffer.
226  * \ingroup internal
227  */
229  {
230  public:
231  ~buffer_reader();
232 
233  /*!
234  * Declares the sample delay for this reader.
235  *
236  * See gr::block::declare_sample_delay for details.
237  *
238  * \param delay The new sample delay
239  */
240  void declare_sample_delay(unsigned delay);
241 
242  /*!
243  * Gets the sample delay for this reader.
244  *
245  * See gr::block::sample_delay for details.
246  */
247  unsigned sample_delay() const;
248 
249  /*!
250  * \brief Return number of items available for reading.
251  */
252  int items_available() const;
253 
254  /*!
255  * \brief Return buffer this reader reads from.
256  */
257  buffer_sptr buffer() const { return d_buffer; }
258 
259  /*!
260  * \brief Return maximum number of items that could ever be available for reading.
261  * This is used as a sanity check in the scheduler to avoid looping forever.
262  */
263  int max_possible_items_available() const { return d_buffer->d_bufsize - 1; }
264 
265  /*!
266  * \brief return pointer to read buffer.
267  *
268  * The return value points to items_available() number of items
269  */
270  const void *read_pointer();
271 
272  /*
273  * \brief tell buffer we read \p items from it
274  */
275  void update_read_pointer(int nitems);
276 
277  void set_done(bool done) { d_buffer->set_done(done); }
278  bool done() const { return d_buffer->done(); }
279 
280  gr::thread::mutex *mutex() { return d_buffer->mutex(); }
281 
282  uint64_t nitems_read() { return d_abs_read_offset; }
283 
284  size_t get_sizeof_item() { return d_buffer->get_sizeof_item(); }
285 
286  /*!
287  * \brief Return the block that reads via this reader.
288  *
289  */
290  block_sptr link() { return block_sptr(d_link); }
291 
292  /*!
293  * \brief Given a [start,end), returns a vector all tags in the range.
294  *
295  * Get a vector of tags in given range. Range of counts is from start to end-1.
296  *
297  * Tags are tuples of:
298  * (item count, source id, key, value)
299  *
300  * \param v a vector reference to return tags into
301  * \param abs_start a uint64 count of the start of the range of interest
302  * \param abs_end a uint64 count of the end of the range of interest
303  * \param id the unique ID of the block to make sure already deleted tags are not returned
304  */
305  void get_tags_in_range(std::vector<tag_t> &v,
306  uint64_t abs_start,
307  uint64_t abs_end,
308  long id);
309 
310  // -------------------------------------------------------------------------
311 
312  private:
313  friend class buffer;
315  buffer_add_reader(buffer_sptr buf, int nzero_preload, block_sptr link, int delay);
316 
317  buffer_sptr d_buffer;
318  unsigned int d_read_index; // in items [0,d->buffer.d_bufsize)
319  uint64_t d_abs_read_offset; // num items seen since the start
320  boost::weak_ptr<block> d_link; // block that reads via this buffer reader
321  unsigned d_attr_delay; // sample delay attribute for tag propagation
322 
323  //! constructor is private. Use gr::buffer::add_reader to create instances
324  buffer_reader(buffer_sptr buffer, unsigned int read_index,
325  block_sptr link);
326  };
327 
328  //! returns # of buffer_readers currently allocated
330 
331 } /* namespace gr */
332 
333 #endif /* INCLUDED_GR_RUNTIME_BUFFER_H */
buffer_sptr buffer() const
Return buffer this reader reads from.
Definition: buffer.h:257
Definition: tags.h:31
How we keep track of the readers of a gr::buffer.
Definition: buffer.h:228
unsigned d_max_reader_delay
Definition: buffer.h:144
void set_done(bool done)
Definition: buffer.h:277
char * d_base
Definition: buffer.h:140
uint64_t nitems_read()
Definition: buffer.h:282
gr::thread::mutex * mutex()
Definition: buffer.h:94
int max_possible_items_available() const
Return maximum number of items that could ever be available for reading. This is used as a sanity che...
Definition: buffer.h:263
std::deque< tag_t >::iterator get_tags_end()
Definition: buffer.h:129
GR_RUNTIME_API buffer_reader_sptr buffer_add_reader(buffer_sptr buf, int nzero_preload, block_sptr link=block_sptr(), int delay=0)
Create a new gr::buffer_reader and attach it to buffer buf.
Definition: cc_common.h:45
std::deque< tag_t >::iterator get_tags_begin()
Definition: buffer.h:128
#define GR_RUNTIME_API
Definition: gnuradio-runtime/include/gnuradio/api.h:30
shared_ptr documentation stub
Definition: shared_ptr_docstub.h:15
bool done() const
Definition: buffer.h:278
Single writer, multiple reader fifo.
Definition: buffer.h:55
block_sptr link()
Return the block that reads via this reader.
Definition: buffer.h:290
size_t get_sizeof_item()
Definition: buffer.h:98
size_t get_sizeof_item()
Definition: buffer.h:284
unsigned __int64 uint64_t
Definition: stdint.h:90
gr::thread::mutex * mutex()
Definition: buffer.h:280
GR_RUNTIME_API long buffer_ncurrently_allocated()
returns # of buffers currently allocated
block_sptr link()
Return the block that writes to this buffer.
Definition: buffer.h:89
buffer_reader * reader(size_t index)
Definition: buffer.h:92
size_t nreaders() const
Definition: buffer.h:91
uint64_t nitems_written()
Definition: buffer.h:96
boost::mutex mutex
Definition: thread.h:46
bool done() const
Definition: buffer.h:84
int bufsize() const
return size of this buffer in items
Definition: buffer.h:68
unsigned int d_bufsize
Definition: buffer.h:141
GR_RUNTIME_API buffer_sptr make_buffer(int nitems, size_t sizeof_item, block_sptr link=block_sptr())
Allocate a buffer that holds at least nitems of size sizeof_item.
GR_RUNTIME_API long buffer_reader_ncurrently_allocated()
returns # of buffer_readers currently allocated