GNU Radio Manual and C++ API Reference  3.10.0.0
The Free & Open Software Radio Ecosystem
buffer_single_mapped.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2020 Free Software Foundation, Inc.
4  *
5  * This file is part of GNU Radio
6  *
7  * SPDX-License-Identifier: GPL-3.0-or-later
8  *
9  */
10 
11 #ifndef INCLUDED_GR_RUNTIME_BUFFER_SINGLE_MAPPED_H
12 #define INCLUDED_GR_RUNTIME_BUFFER_SINGLE_MAPPED_H
13 
14 #include <cstddef>
15 #include <functional>
16 
17 #include <gnuradio/api.h>
18 #include <gnuradio/buffer.h>
19 #include <gnuradio/buffer_reader.h>
20 #include <gnuradio/logger.h>
21 #include <gnuradio/runtime_types.h>
22 
23 namespace gr {
24 
25 /*!
26  * \brief A single mapped buffer where wrapping conditions are handled explicitly
27  * via input/output_blocked_callback functions called from block_executor.
28  * \ingroup internal
29  */
31 {
32 public:
35 
37 
38  /*!
39  * \brief Return the block that owns this buffer.
40  */
41  block_sptr buf_owner() { return d_buf_owner; }
42 
43  /*!
44  * \brief return number of items worth of space available for writing
45  */
46  int space_available() override;
47 
48  void update_reader_block_history(unsigned history, int delay) override;
49 
50  /*!
51  * \brief Return true if thread is ready to call input_blocked_callback,
52  * false otherwise
53  */
54  bool input_blkd_cb_ready(int items_required, unsigned read_index) override;
55 
56  /*!
57  * \brief Callback function that the scheduler will call when it determines
58  * that the input is blocked. Override this function if needed.
59  */
60  bool input_blocked_callback(int items_required,
61  int items_avail,
62  unsigned read_index) override = 0;
63 
64  /*!
65  * \brief Return true if thread is ready to call the callback, false otherwise
66  */
67  bool output_blkd_cb_ready(int output_multiple) override;
68 
69  /*!
70  * \brief Callback function that the scheduler will call when it determines
71  * that the output is blocked
72  */
73  bool output_blocked_callback(int output_multiple, bool force) override = 0;
74 
75 protected:
76  /*!
77  * \brief Make reasonable attempt to adjust nitems based on read/write
78  * granularity then delegate actual allocation to do_allocate_buffer().
79  * @return true iff successful.
80  */
81  bool allocate_buffer(int nitems) override;
82 
83  /*!
84  * \brief Do actual buffer allocation. This is intended (required) to be
85  * handled by the derived class.
86  */
87  virtual bool do_allocate_buffer(size_t final_nitems, size_t sizeof_item) = 0;
88 
89  unsigned index_add(unsigned a, unsigned b) override
90  {
91  unsigned s = a + b;
92 
93  if (s >= d_bufsize)
94  s -= d_bufsize;
95 
96  assert(s < d_bufsize);
97  return s;
98  }
99 
100  unsigned index_sub(unsigned a, unsigned b) override
101  {
102  // NOTE: a is writer ptr and b is read ptr
103  int s = a - b;
104 
105  if (s < 0)
106  s = d_bufsize - b;
107 
108  assert((unsigned)s < d_bufsize);
109  return s;
110  }
111 
112 
113  friend class buffer_reader;
114 
115  friend GR_RUNTIME_API buffer_sptr make_buffer(int nitems,
116  size_t sizeof_item,
117  uint64_t downstream_lcm_nitems,
118  block_sptr link,
119  block_sptr buf_owner);
120 
121  block_sptr d_buf_owner; // block that "owns" this buffer
122 
123  std::unique_ptr<char[]> d_buffer;
124 
125  /*!
126  * \brief constructor is private. Use gr_make_buffer to create instances.
127  *
128  * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
129  *
130  * \param nitems is the minimum number of items the buffer will hold.
131  * \param sizeof_item is the size of an item in bytes.
132  * \param downstream_lcm_nitems is the least common multiple of the items to
133  * read by downstream blocks
134  * \param downstream_max_out_mult is the maximum output multiple of all
135  * downstream blocks
136  * \param link is the block that writes to this buffer.
137  * \param buf_owner if the block that owns the buffer which may or may not
138  * be the same as the block that writes to this buffer
139  *
140  * The total size of the buffer will be rounded up to a system
141  * dependent boundary. This is typically the system page size, but
142  * under MS windows is 64KB.
143  */
145  size_t sizeof_item,
146  uint64_t downstream_lcm_nitems,
147  uint32_t downstream_max_out_mult,
148  block_sptr link,
149  block_sptr buf_owner);
150 
151  /*!
152  * \brief Abstracted logic for the input blocked callback function.
153  *
154  * This function contains the logic for the input blocked callback however
155  * the data adjustment portion of the callback has been abstracted to allow
156  * the caller to pass in the desired buffer and corresponding buffer
157  * manipulation functions (memcpy and memmove).
158  *
159  * The input blocked callback is called when a reader needs to read more
160  * data than is available in a buffer and the available data is located at
161  * the end of the buffer. The input blocked callback will attempt to move
162  * any data located at the beginning of the buffer "down", and will then
163  * attempt to copy from the end of the buffer back to the beginning of the
164  * buffer. This process explicitly handles wrapping for a single mapped
165  * buffer and will realign the data at the beginning of the buffer such
166  * that the reader is able to read the available data and becomes unblocked.
167  *
168  * \param items_required is the number of items required by the reader
169  * \param items_avail is the number of items available
170  * \param read_index is the current read index of the buffer reader caller
171  * \param buffer_ptr is the pointer to the desired buffer
172  * \param memcpy_func is a pointer to a memcpy function appropriate for the
173  * the passed in buffer
174  * \param memmove_func is a pointer to a memmove function appropriate for
175  * the passed in buffer
176  */
177  virtual bool input_blocked_callback_logic(int items_required,
178  int items_avail,
179  unsigned read_index,
180  char* buffer_ptr,
181  mem_func_t const& memcpy_func,
182  mem_func_t const& memmove_func);
183 
184  /*!
185  * \brief Abstracted logic for the output blocked callback function.
186  *
187  * This function contains the logic for the output blocked callback however
188  * the data adjustment portion of the callback has been abstracted to allow
189  * the caller to pass in the desired buffer and corresponding buffer
190  * manipulation functions (memcpy and memmove).
191  *
192  * The output blocked callback is called when a block needs to write data
193  * to the end of a single mapped buffer but not enough free space exists to
194  * write the data before the end of the buffer is reached. The output blocked
195  * callback will attempt to copy data located towards the end of a single
196  * mapped buffer back to the beginning of the buffer. This process explicitly
197  * handles wrapping for a single mapped buffer and will realign data located
198  * at the end of a buffer back to the beginning of the buffer such that the
199  * writing block can write its output into the buffer after the existing data.
200  *
201  * \param output_multiple
202  * \param force run the callback disregarding the internal checks
203  * \param buffer_ptr is the pointer to the desired buffer
204  * \param memmove_func is a pointer to a memmove function appropriate for
205  * the passed in buffer
206  */
207  virtual bool output_blocked_callback_logic(int output_multiple,
208  bool force,
209  char* buffer_ptr,
210  mem_func_t const& memmove_func);
211 };
212 
213 } /* namespace gr */
214 
215 
216 #endif /* INCLUDED_GR_RUNTIME_BUFFER_SINGLE_MAPPED_H */
How we keep track of the readers of a gr::buffer.
Definition: buffer_reader.h:49
A single mapped buffer where wrapping conditions are handled explicitly via input/output_blocked_call...
Definition: buffer_single_mapped.h:31
unsigned index_sub(unsigned a, unsigned b) override
Decrement read or write index for this buffer.
Definition: buffer_single_mapped.h:100
bool input_blocked_callback(int items_required, int items_avail, unsigned read_index) override=0
Callback function that the scheduler will call when it determines that the input is blocked....
~buffer_single_mapped() override
bool allocate_buffer(int nitems) override
Make reasonable attempt to adjust nitems based on read/write granularity then delegate actual allocat...
block_sptr d_buf_owner
Definition: buffer_single_mapped.h:121
friend GR_RUNTIME_API buffer_sptr make_buffer(int nitems, size_t sizeof_item, uint64_t downstream_lcm_nitems, block_sptr link, block_sptr buf_owner)
buffer_single_mapped(int nitems, size_t sizeof_item, uint64_t downstream_lcm_nitems, uint32_t downstream_max_out_mult, block_sptr link, block_sptr buf_owner)
constructor is private. Use gr_make_buffer to create instances.
bool output_blkd_cb_ready(int output_multiple) override
Return true if thread is ready to call the callback, false otherwise.
bool input_blkd_cb_ready(int items_required, unsigned read_index) override
Return true if thread is ready to call input_blocked_callback, false otherwise.
std::unique_ptr< char[]> d_buffer
Definition: buffer_single_mapped.h:123
virtual bool input_blocked_callback_logic(int items_required, int items_avail, unsigned read_index, char *buffer_ptr, mem_func_t const &memcpy_func, mem_func_t const &memmove_func)
Abstracted logic for the input blocked callback function.
gr::logger_ptr d_logger
Definition: buffer_single_mapped.h:33
bool output_blocked_callback(int output_multiple, bool force) override=0
Callback function that the scheduler will call when it determines that the output is blocked.
void update_reader_block_history(unsigned history, int delay) override
unsigned index_add(unsigned a, unsigned b) override
Increment read or write index for this buffer.
Definition: buffer_single_mapped.h:89
block_sptr buf_owner()
Return the block that owns this buffer.
Definition: buffer_single_mapped.h:41
int space_available() override
return number of items worth of space available for writing
virtual bool do_allocate_buffer(size_t final_nitems, size_t sizeof_item)=0
Do actual buffer allocation. This is intended (required) to be handled by the derived class.
virtual bool output_blocked_callback_logic(int output_multiple, bool force, char *buffer_ptr, mem_func_t const &memmove_func)
Abstracted logic for the output blocked callback function.
gr::logger_ptr d_debug_logger
Definition: buffer_single_mapped.h:34
Single writer, multiple reader fifo.
Definition: buffer.h:67
#define GR_RUNTIME_API
Definition: gnuradio-runtime/include/gnuradio/api.h:18
GNU Radio logging wrapper.
Definition: basic_block.h:29
std::function< void *(void *, const void *, std::size_t)> mem_func_t
Definition: buffer.h:36
std::shared_ptr< logger > logger_ptr
Definition: logger.h:207