Loading...
Searching...
No Matches
buffer_single_mapped.h
Go to the documentation of this file.
/* -*- c++ -*- */
/*
* Copyright 2020 Free Software Foundation, Inc.
*
* This file is part of GNU Radio
*
* SPDX-License-Identifier: GPL-3.0-or-later
*
*/
#ifndef INCLUDED_GR_RUNTIME_BUFFER_SINGLE_MAPPED_H
#define INCLUDED_GR_RUNTIME_BUFFER_SINGLE_MAPPED_H
#include <cstddef>
#include <gnuradio/api.h>
#include <gnuradio/buffer.h>
#include <gnuradio/buffer_reader.h>
#include <gnuradio/logger.h>
#include <gnuradio/runtime_types.h>
namespace gr {
/*!
* \brief A single mapped buffer where wrapping conditions are handled explicitly
* via input/output_blocked_callback functions called from block_executor.
* \ingroup internal
*/
class GR_RUNTIME_API buffer_single_mapped : public buffer
{
public:
gr::logger_ptr d_logger;
gr::logger_ptr d_debug_logger;
~buffer_single_mapped() override;
/*!
* \brief Return the block that owns this buffer.
*/
block_sptr buf_owner() { return d_buf_owner; }
/*!
* \brief return number of items worth of space available for writing
*/
int space_available() override;
void update_reader_block_history(unsigned history, int delay) override;
/*!
* \brief Return true if thread is ready to call input_blocked_callback,
* false otherwise
*/
bool input_blkd_cb_ready(int items_required, unsigned read_index) override;
/*!
* \brief Callback function that the scheduler will call when it determines
* that the input is blocked. Override this function if needed.
*/
bool input_blocked_callback(int items_required,
int items_avail,
unsigned read_index) override = 0;
/*!
* \brief Return true if thread is ready to call the callback, false otherwise
*/
bool output_blkd_cb_ready(int output_multiple) override;
/*!
* \brief Callback function that the scheduler will call when it determines
* that the output is blocked
*/
bool output_blocked_callback(int output_multiple, bool force) override = 0;
protected:
/*!
* \brief Make reasonable attempt to adjust nitems based on read/write
* granularity then delegate actual allocation to do_allocate_buffer().
* @return true iff successful.
*/
bool allocate_buffer(int nitems) override;
/*!
* \brief Do actual buffer allocation. This is intended (required) to be
* handled by the derived class.
*/
virtual bool do_allocate_buffer(size_t final_nitems, size_t sizeof_item) = 0;
unsigned index_add(unsigned a, unsigned b) override
{
unsigned s = a + b;
if (s >= d_bufsize)
s -= d_bufsize;
assert(s < d_bufsize);
return s;
}
unsigned index_sub(unsigned a, unsigned b) override
{
// NOTE: a is writer ptr and b is read ptr
int s = a - b;
if (s < 0)
s = d_bufsize - b;
assert((unsigned)s < d_bufsize);
return s;
}
friend class buffer_reader;
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);
block_sptr d_buf_owner; // block that "owns" this buffer
std::unique_ptr<char[]> d_buffer;
/*!
* \brief constructor is private. Use gr_make_buffer to create instances.
*
* Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
*
* \param nitems is the minimum number of items the buffer will hold.
* \param sizeof_item is the size of an item in bytes.
* \param downstream_lcm_nitems is the least common multiple of the items to
* read by downstream blocks
* \param downstream_max_out_mult is the maximum output multiple of all
* downstream blocks
* \param link is the block that writes to this buffer.
* \param buf_owner if the block that owns the buffer which may or may not
* be the same as the block that writes to this buffer
*
* The total size of the buffer will be rounded up to a system
* dependent boundary. This is typically the system page size, but
* under MS windows is 64KB.
*/
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);
/*!
* \brief Abstracted logic for the input blocked callback function.
*
* This function contains the logic for the input blocked callback however
* the data adjustment portion of the callback has been abstracted to allow
* the caller to pass in the desired buffer and corresponding buffer
* manipulation functions (memcpy and memmove).
*
* The input blocked callback is called when a reader needs to read more
* data than is available in a buffer and the available data is located at
* the end of the buffer. The input blocked callback will attempt to move
* any data located at the beginning of the buffer "down", and will then
* attempt to copy from the end of the buffer back to the beginning of the
* buffer. This process explicitly handles wrapping for a single mapped
* buffer and will realign the data at the beginning of the buffer such
* that the reader is able to read the available data and becomes unblocked.
*
* \param items_required is the number of items required by the reader
* \param items_avail is the number of items available
* \param read_index is the current read index of the buffer reader caller
* \param buffer_ptr is the pointer to the desired buffer
* \param memcpy_func is a pointer to a memcpy function appropriate for the
* the passed in buffer
* \param memmove_func is a pointer to a memmove function appropriate for
* the passed in buffer
*/
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);
/*!
* \brief Abstracted logic for the output blocked callback function.
*
* This function contains the logic for the output blocked callback however
* the data adjustment portion of the callback has been abstracted to allow
* the caller to pass in the desired buffer and corresponding buffer
* manipulation functions (memcpy and memmove).
*
* The output blocked callback is called when a block needs to write data
* to the end of a single mapped buffer but not enough free space exists to
* write the data before the end of the buffer is reached. The output blocked
* callback will attempt to copy data located towards the end of a single
* mapped buffer back to the beginning of the buffer. This process explicitly
* handles wrapping for a single mapped buffer and will realign data located
* at the end of a buffer back to the beginning of the buffer such that the
* writing block can write its output into the buffer after the existing data.
*
* \param output_multiple
* \param force run the callback disregarding the internal checks
* \param buffer_ptr is the pointer to the desired buffer
* \param memmove_func is a pointer to a memmove function appropriate for
* the passed in buffer
*/
virtual bool output_blocked_callback_logic(int output_multiple,
bool force,
char* buffer_ptr,
mem_func_t const& memmove_func);
};
} /* namespace gr */
#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