GNU Radio C++ API Reference: buffer_single_mapped.h Source File

| GNU Radio C++ API Reference 3.10.12.0 The Free & Open Software Radio Ecosystem |

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