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