3 * Copyright 2004 Free Software Foundation, Inc.
5 * This file is part of GNU Radio
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)
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.
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.
23 #ifndef INCLUDED_GR_BUFFER_H
24 #define INCLUDED_GR_BUFFER_H
26 #include <gr_runtime_types.h>
27 #include <boost/weak_ptr.hpp>
28 #include <boost/thread.hpp>
33 * \brief Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
35 * The total size of the buffer will be rounded up to a system
36 * dependent boundary. This is typically the system page size, but
37 * under MS windows is 64KB.
39 * \param nitems is the minimum number of items the buffer will hold.
40 * \param sizeof_item is the size of an item in bytes.
41 * \param link is the block that writes to this buffer.
43 gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link=gr_block_sptr());
47 * \brief Single writer, multiple reader fifo.
53 typedef boost::unique_lock<boost::mutex> scoped_lock;
55 virtual ~gr_buffer ();
58 * \brief return number of items worth of space available for writing
60 int space_available ();
63 * \brief return size of this buffer in items
65 int bufsize() const { return d_bufsize; }
68 * \brief return pointer to write buffer.
70 * The return value points at space that can hold at least
71 * space_available() items.
73 void *write_pointer ();
76 * \brief tell buffer that we wrote \p nitems into it
78 void update_write_pointer (int nitems);
80 void set_done (bool done);
81 bool done () const { return d_done; }
84 * \brief Return the block that writes to this buffer.
86 gr_block_sptr link() { return gr_block_sptr(d_link); }
88 size_t nreaders() const { return d_readers.size(); }
89 gr_buffer_reader* reader(size_t index) { return d_readers[index]; }
91 boost::mutex *mutex() { return &d_mutex; }
93 // -------------------------------------------------------------------------
97 friend class gr_buffer_reader;
98 friend gr_buffer_sptr gr_make_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
99 friend gr_buffer_reader_sptr gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
102 char *d_base; // base address of buffer
103 unsigned int d_bufsize; // in items
105 gr_vmcircbuf *d_vmcircbuf;
106 size_t d_sizeof_item; // in bytes
107 std::vector<gr_buffer_reader *> d_readers;
108 boost::weak_ptr<gr_block> d_link; // block that writes to this buffer
111 // The mutex protects d_write_index, d_done and the d_read_index's in the buffer readers.
113 boost::mutex d_mutex;
114 unsigned int d_write_index; // in items [0,d_bufsize)
118 index_add (unsigned a, unsigned b)
125 assert (s < d_bufsize);
130 index_sub (unsigned a, unsigned b)
137 assert ((unsigned) s < d_bufsize);
141 virtual bool allocate_buffer (int nitems, size_t sizeof_item);
144 * \brief constructor is private. Use gr_make_buffer to create instances.
146 * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
148 * \param nitems is the minimum number of items the buffer will hold.
149 * \param sizeof_item is the size of an item in bytes.
150 * \param link is the block that writes to this buffer.
152 * The total size of the buffer will be rounded up to a system
153 * dependent boundary. This is typically the system page size, but
154 * under MS windows is 64KB.
156 gr_buffer (int nitems, size_t sizeof_item, gr_block_sptr link);
159 * \brief disassociate \p reader from this buffer
161 void drop_reader (gr_buffer_reader *reader);
166 * \brief Create a new gr_buffer_reader and attach it to buffer \p buf
167 * \param buf is the buffer the \p gr_buffer_reader reads from.
168 * \param nzero_preload -- number of zero items to "preload" into buffer.
169 * \param link is the block that reads from the buffer using this gr_buffer_reader.
171 gr_buffer_reader_sptr
172 gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link=gr_block_sptr());
174 //! returns # of gr_buffers currently allocated
175 long gr_buffer_ncurrently_allocated ();
178 // ---------------------------------------------------------------------------
181 * \brief How we keep track of the readers of a gr_buffer.
185 class gr_buffer_reader {
188 typedef gr_buffer::scoped_lock scoped_lock;
190 ~gr_buffer_reader ();
193 * \brief Return number of items available for reading.
195 int items_available () const;
198 * \brief Return buffer this reader reads from.
200 gr_buffer_sptr buffer () const { return d_buffer; }
204 * \brief Return maximum number of items that could ever be available for reading.
205 * This is used as a sanity check in the scheduler to avoid looping forever.
207 int max_possible_items_available () const { return d_buffer->d_bufsize - 1; }
210 * \brief return pointer to read buffer.
212 * The return value points to items_available() number of items
214 const void *read_pointer ();
217 * \brief tell buffer we read \p items from it
219 void update_read_pointer (int nitems);
221 void set_done (bool done) { d_buffer->set_done (done); }
222 bool done () const { return d_buffer->done (); }
224 boost::mutex *mutex() { return d_buffer->mutex(); }
228 * \brief Return the block that reads via this reader.
230 gr_block_sptr link() { return gr_block_sptr(d_link); }
232 // -------------------------------------------------------------------------
236 friend class gr_buffer;
237 friend gr_buffer_reader_sptr
238 gr_buffer_add_reader (gr_buffer_sptr buf, int nzero_preload, gr_block_sptr link);
241 gr_buffer_sptr d_buffer;
242 unsigned int d_read_index; // in items [0,d->buffer.d_bufsize)
243 boost::weak_ptr<gr_block> d_link; // block that reads via this buffer reader
245 //! constructor is private. Use gr_buffer::add_reader to create instances
246 gr_buffer_reader (gr_buffer_sptr buffer, unsigned int read_index, gr_block_sptr link);
249 //! returns # of gr_buffer_readers currently allocated
250 long gr_buffer_reader_ncurrently_allocated ();
253 #endif /* INCLUDED_GR_BUFFER_H */