GNU Radio C++ API Reference: gr::buffer_single_mapped Class Reference

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

Loading...
Searching...
No Matches
gr::buffer_single_mapped Class Referenceabstract
Implementation Details

A single mapped buffer where wrapping conditions are handled explicitly via input/output_blocked_callback functions called from block_executor. More...

`#include <gnuradio/buffer_single_mapped.h>`

## Public Member Functions
| ~buffer_single_mapped () override
block_sptr | buf_owner ()
| Return the block that owns this buffer.
int | space_available () override
| return number of items worth of space available for writing
void | update_reader_block_history (unsigned history, int delay) override
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.
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. Override this function if needed.
bool | output_blkd_cb_ready (int output_multiple) override
| Return true if thread is ready to call the callback, false otherwise.
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.
Public Member Functions inherited from gr::buffer
| ~buffer () override
buffer_mapping_type | get_mapping_type ()
| return the buffer's mapping type
unsigned int | bufsize () const
| return size of this buffer in items
const char * | base () const
| return the base address of the buffer
virtual void * | write_pointer ()
| return pointer to write buffer.
virtual const void * | _read_pointer (unsigned int read_index)
| return pointer to read buffer.
void | update_write_pointer (int nitems)
| tell buffer that we wrote `nitems` into it
void | set_done (bool done)
bool | done () const
block_sptr | link ()
| Return the block that writes to this buffer.
size_t | nreaders () const
buffer_reader * | reader (size_t index)
gr::thread::mutex * | mutex ()
uint64_t | nitems_written ()
void | reset_nitem_counter ()
size_t | get_sizeof_item ()
uint64_t | get_downstream_lcm_nitems ()
uint32_t | get_max_reader_output_multiple ()
void | add_item_tag (const tag_t &tag)
| Adds a new tag to the buffer.
void | remove_item_tag (const tag_t &tag, long id)
| Removes an existing tag from the buffer.
void | prune_tags (uint64_t max_time)
| Removes all tags before `max_time` from buffer.
std::multimap< uint64_t, tag_t >::iterator | get_tags_begin ()
std::multimap< uint64_t, tag_t >::iterator | get_tags_end ()
std::multimap< uint64_t, tag_t >::iterator | get_tags_lower_bound (uint64_t x)
std::multimap< uint64_t, tag_t >::iterator | get_tags_upper_bound (uint64_t x)
virtual void | post_work (int nitems)=0
| Function to be executed after this object's owner completes the call to general_work().
void | increment_active ()
| Increment the number of active pointers for this buffer.
void | decrement_active ()
| Decrement the number of active pointers for this buffer and signal anyone waiting when the count reaches zero.
void | on_lock (gr::thread::scoped_lock &lock) override
| "on_lock" function from the custom_lock_if.
void | on_unlock () override
| "on_unlock" function from the custom_lock_if.
void | set_transfer_type (const transfer_type &type)
| Assign buffer's transfer_type.
Public Member Functions inherited from gr::custom_lock_if
virtual | ~custom_lock_if ()

## Public Attributes
gr::logger_ptr | d_logger
gr::logger_ptr | d_debug_logger
Public Attributes inherited from gr::buffer
gr::logger_ptr | d_logger
gr::logger_ptr | d_debug_logger

## Protected Member Functions
bool | allocate_buffer (int nitems) override
| Make reasonable attempt to adjust nitems based on read/write granularity then delegate actual allocation to 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.
unsigned | index_add (unsigned a, unsigned b) override
| Increment read or write index for this buffer.
unsigned | index_sub (unsigned a, unsigned b) override
| Decrement read or write index for this buffer.
| 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.
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.
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.
Protected Member Functions inherited from gr::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.
void | drop_reader (buffer_reader *reader)
| disassociate `reader` from this buffer

## Protected Attributes
block_sptr | d_buf_owner
std::unique_ptr< char[]> | d_buffer
Protected Attributes inherited from gr::buffer
char * | d_base
unsigned int | d_bufsize
buffer_mapping_type | d_buf_map_type
unsigned | d_max_reader_delay
unsigned | d_max_reader_history
bool | d_has_history
size_t | d_sizeof_item
std::vector< buffer_reader * > | d_readers
std::weak_ptr< block > | d_link
gr::thread::mutex | d_mutex
unsigned int | d_write_index
uint64_t | d_abs_write_offset
bool | d_done
std::multimap< uint64_t, tag_t > | d_item_tags
uint64_t | d_last_min_items_read
gr::thread::condition_variable | d_cv
bool | d_callback_flag
uint32_t | d_active_pointer_counter
uint64_t | d_downstream_lcm_nitems
uint64_t | d_write_multiple
uint32_t | d_max_reader_output_multiple
transfer_type | d_transfer_type

## Friends
class | buffer_reader
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)

## Detailed Description

A single mapped buffer where wrapping conditions are handled explicitly via input/output_blocked_callback functions called from block_executor.

## Constructor & Destructor Documentation

## ◆ ~buffer_single_mapped()

gr::buffer_single_mapped::~buffer_single_mapped | ( |  | ) |
| override

## ◆ buffer_single_mapped()

gr::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 )
| protected

constructor is private. Use gr_make_buffer to create instances.

Allocate a buffer that holds at least `nitems` of size `sizeof_item`.

Parameters

  nitems | is the minimum number of items the buffer will hold.
  sizeof_item | is the size of an item in bytes.
  downstream_lcm_nitems | is the least common multiple of the items to read by downstream blocks
  downstream_max_out_mult | is the maximum output multiple of all downstream blocks
  link | is the block that writes to this buffer.
  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.

References buf_owner(), and gr::buffer::link().

## Member Function Documentation

## ◆ allocate_buffer()

bool gr::buffer_single_mapped::allocate_buffer | ( | int | nitems | ) |
| overrideprotectedvirtual

Make reasonable attempt to adjust nitems based on read/write granularity then delegate actual allocation to do_allocate_buffer().

Returns
  true iff successful.

Reimplemented from gr::buffer.

## ◆ buf_owner()

block_sptr gr::buffer_single_mapped::buf_owner | ( |  | ) |
| inline

Return the block that owns this buffer.

References d_buf_owner.

Referenced by buffer_single_mapped(), make_buffer, gr::host_buffer::make_buffer(), and gr::host_buffer::make_host_buffer().

## ◆ do_allocate_buffer()

virtual bool gr::buffer_single_mapped::do_allocate_buffer | ( | size_t | final_nitems,
|  | size_t | sizeof_item )
| protectedpure virtual

Do actual buffer allocation. This is intended (required) to be handled by the derived class.

Implemented in gr::host_buffer.

## ◆ index_add()

unsigned gr::buffer_single_mapped::index_add | ( | unsigned | a,
|  | unsigned | b )
| inlineoverrideprotectedvirtual

Increment read or write index for this buffer.

Implements gr::buffer.

References gr::buffer::d_bufsize.

## ◆ index_sub()

unsigned gr::buffer_single_mapped::index_sub | ( | unsigned | a,
|  | unsigned | b )
| inlineoverrideprotectedvirtual

Decrement read or write index for this buffer.

Implements gr::buffer.

References gr::buffer::d_bufsize.

## ◆ input_blkd_cb_ready()

bool gr::buffer_single_mapped::input_blkd_cb_ready | ( | int | items_required,
|  | unsigned | read_index )
| overridevirtual

Return true if thread is ready to call input_blocked_callback, false otherwise.

Reimplemented from gr::buffer.

## ◆ input_blocked_callback()

bool gr::buffer_single_mapped::input_blocked_callback | ( | int | items_required,
|  | int | items_avail,
|  | unsigned | read_index )
| overridepure virtual

Callback function that the scheduler will call when it determines that the input is blocked. Override this function if needed.

Reimplemented from gr::buffer.

Implemented in gr::host_buffer.

## ◆ input_blocked_callback_logic()

virtual bool gr::buffer_single_mapped::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 )
| protectedvirtual

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.

Parameters

  items_required | is the number of items required by the reader
  items_avail | is the number of items available
  read_index | is the current read index of the buffer reader caller
  buffer_ptr | is the pointer to the desired buffer
  memcpy_func | is a pointer to a memcpy function appropriate for the the passed in buffer
  memmove_func | is a pointer to a memmove function appropriate for the passed in buffer

## ◆ output_blkd_cb_ready()

bool gr::buffer_single_mapped::output_blkd_cb_ready | ( | int | output_multiple | ) |
| overridevirtual

Return true if thread is ready to call the callback, false otherwise.

Reimplemented from gr::buffer.

## ◆ output_blocked_callback()

bool gr::buffer_single_mapped::output_blocked_callback | ( | int | output_multiple,
|  | bool | force )
| overridepure virtual

Callback function that the scheduler will call when it determines that the output is blocked.

Reimplemented from gr::buffer.

Implemented in gr::host_buffer.

## ◆ output_blocked_callback_logic()

virtual bool gr::buffer_single_mapped::output_blocked_callback_logic | ( | int | output_multiple,
|  | bool | force,
|  | char * | buffer_ptr,
|  | mem_func_t const & | memmove_func )
| protectedvirtual

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.

Parameters

  output_multiple |
  force | run the callback disregarding the internal checks
  buffer_ptr | is the pointer to the desired buffer
  memmove_func | is a pointer to a memmove function appropriate for the passed in buffer

## ◆ space_available()

int gr::buffer_single_mapped::space_available | ( |  | ) |
| overridevirtual

return number of items worth of space available for writing

Implements gr::buffer.

## ◆ update_reader_block_history()

void gr::buffer_single_mapped::update_reader_block_history | ( | unsigned | history,
|  | int | delay )
| overridevirtual

Reimplemented from gr::buffer.

## Friends And Related Symbol Documentation

## ◆ buffer_reader

friend class buffer_reader
| friend

References buffer_reader.

Referenced by buffer_reader.

## ◆ make_buffer

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 )
| friend

References buf_owner(), GR_RUNTIME_API, and gr::buffer::link().

## Member Data Documentation

## ◆ d_buf_owner

block_sptr gr::buffer_single_mapped::d_buf_owner
| protected

Referenced by buf_owner().

## ◆ d_buffer

std::unique_ptr<char[]> gr::buffer_single_mapped::d_buffer
| protected

## ◆ d_debug_logger

gr::logger_ptr gr::buffer_single_mapped::d_debug_logger

## ◆ d_logger

gr::logger_ptr gr::buffer_single_mapped::d_logger

The documentation for this class was generated from the following file:

- buffer_single_mapped.h