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

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

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

Single writer, multiple reader fifo. More...

`#include <gnuradio/buffer.h>`

## Public Member Functions
| ~buffer () override
buffer_mapping_type | get_mapping_type ()
| return the buffer's mapping type
virtual int | space_available ()=0
| return number of items worth of space available for writing
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 ()
virtual void | update_reader_block_history (unsigned history, int delay)
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().
virtual bool | input_blkd_cb_ready (int items_required, unsigned read_index)
| Returns true when the current thread is ready to call the callback, false otherwise. Note if input_blocked_callback is overridden then this function should also be overridden.
virtual bool | input_blocked_callback (int items_required, int items_avail, unsigned read_index)
| Callback function that the scheduler will call when it determines that the input is blocked. Override this function if needed.
virtual bool | output_blkd_cb_ready (int output_multiple)
| Returns true if the current thread is ready to execute output_blocked_callback(), false otherwise. Note if the default output_blocked_callback is overridden this function should also be overridden.
virtual bool | output_blocked_callback (int output_multiple, bool force=false)
| Callback function that the scheduler will call when it determines that the output is blocked. Override this function if needed.
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

## Protected Member Functions
virtual unsigned | index_add (unsigned a, unsigned b)=0
| Increment read or write index for this buffer.
virtual unsigned | index_sub (unsigned a, unsigned b)=0
| Decrement read or write index for this buffer.
virtual bool | allocate_buffer (int nitems)
| 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
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
class | buffer_reader_sm
std::ostream & | operator<< (std::ostream &os, const buffer &buf)
GR_RUNTIME_API buffer_sptr | make_buffer (int nitems, size_t sizeof_item, uint64_t downstream_lcm_nitems, block_sptr link)
GR_RUNTIME_API buffer_reader_sptr | buffer_add_reader (buffer_sptr buf, int nzero_preload, block_sptr link=block_sptr(), int delay=0)
| Create a new gr::buffer_reader and attach it to buffer `buf`.

## Detailed Description

Single writer, multiple reader fifo.

## Constructor & Destructor Documentation

## ◆ ~buffer()

gr::buffer::~buffer | ( |  | ) |
| override

## ◆ buffer()

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

constructor is private. Use gr_make_buffer to create instances.

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

Parameters

  buftype | is an enum type that describes the buffer TODO: fix me
  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 block(s)
  downstream_max_out_mult | is the maximum output multiple of all downstream blocks
  link | is 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 link().

Referenced by operator<<.

## Member Function Documentation

## ◆ _read_pointer()

virtual const void * gr::buffer::_read_pointer | ( | unsigned int | read_index | ) |
| virtual

return pointer to read buffer.

The return value points to at least items_available() items.

Reimplemented in gr::host_buffer.

## ◆ add_item_tag()

void gr::buffer::add_item_tag | ( | const tag_t & | tag | ) |

Adds a new tag to the buffer.

Parameters

  tag | the new tag

## ◆ allocate_buffer()

virtual bool gr::buffer::allocate_buffer | ( | int | nitems | ) |
| inlineprotectedvirtual

Reimplemented in gr::buffer_double_mapped, and gr::buffer_single_mapped.

## ◆ base()

const char * gr::buffer::base | ( |  | ) | const
| inline

return the base address of the buffer

References d_base.

## ◆ bufsize()

unsigned int gr::buffer::bufsize | ( |  | ) | const
| inline

return size of this buffer in items

References d_bufsize.

## ◆ decrement_active()

void gr::buffer::decrement_active | ( |  | ) |
| inline

Decrement the number of active pointers for this buffer and signal anyone waiting when the count reaches zero.

References d_active_pointer_counter, d_cv, and d_mutex.

## ◆ done()

bool gr::buffer::done | ( |  | ) | const
| inline

References d_done.

Referenced by set_done().

## ◆ drop_reader()

void gr::buffer::drop_reader | ( | buffer_reader * | reader | ) |
| protected

disassociate `reader` from this buffer

References buffer_reader, and reader().

## ◆ get_downstream_lcm_nitems()

uint64_t gr::buffer::get_downstream_lcm_nitems | ( |  | ) |
| inline

References d_downstream_lcm_nitems.

## ◆ get_mapping_type()

buffer_mapping_type gr::buffer::get_mapping_type | ( |  | ) |
| inline

return the buffer's mapping type

References d_buf_map_type.

## ◆ get_max_reader_output_multiple()

uint32_t gr::buffer::get_max_reader_output_multiple | ( |  | ) |
| inline

References d_max_reader_output_multiple.

## ◆ get_sizeof_item()

size_t gr::buffer::get_sizeof_item | ( |  | ) |
| inline

References d_sizeof_item.

## ◆ get_tags_begin()

std::multimap< uint64_t, tag_t >::iterator gr::buffer::get_tags_begin | ( |  | ) |
| inline

References d_item_tags.

## ◆ get_tags_end()

std::multimap< uint64_t, tag_t >::iterator gr::buffer::get_tags_end | ( |  | ) |
| inline

References d_item_tags.

## ◆ get_tags_lower_bound()

std::multimap< uint64_t, tag_t >::iterator gr::buffer::get_tags_lower_bound | ( | uint64_t | x | ) |
| inline

References d_item_tags.

## ◆ get_tags_upper_bound()

std::multimap< uint64_t, tag_t >::iterator gr::buffer::get_tags_upper_bound | ( | uint64_t | x | ) |
| inline

References d_item_tags.

## ◆ increment_active()

void gr::buffer::increment_active | ( |  | ) |
| inline

Increment the number of active pointers for this buffer.

References d_active_pointer_counter, d_callback_flag, d_cv, and d_mutex.

## ◆ index_add()

virtual unsigned gr::buffer::index_add | ( | unsigned | a,
|  | unsigned | b )
| protectedpure virtual

Increment read or write index for this buffer.

Implemented in gr::buffer_double_mapped, and gr::buffer_single_mapped.

## ◆ index_sub()

virtual unsigned gr::buffer::index_sub | ( | unsigned | a,
|  | unsigned | b )
| protectedpure virtual

Decrement read or write index for this buffer.

Implemented in gr::buffer_double_mapped, and gr::buffer_single_mapped.

## ◆ input_blkd_cb_ready()

virtual bool gr::buffer::input_blkd_cb_ready | ( | int | items_required,
|  | unsigned | read_index )
| inlinevirtual

Returns true when the current thread is ready to call the callback, false otherwise. Note if input_blocked_callback is overridden then this function should also be overridden.

Reimplemented in gr::buffer_single_mapped.

## ◆ input_blocked_callback()

virtual bool gr::buffer::input_blocked_callback | ( | int | items_required,
|  | int | items_avail,
|  | unsigned | read_index )
| inlinevirtual

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

Reimplemented in gr::buffer_single_mapped, and gr::host_buffer.

## ◆ link()

block_sptr gr::buffer::link | ( |  | ) |
| inline

Return the block that writes to this buffer.

References d_link.

Referenced by buffer(), buffer_add_reader, gr::buffer_single_mapped::buffer_single_mapped(), make_buffer, gr::buffer_double_mapped::make_buffer, gr::buffer_double_mapped::make_buffer(), gr::buffer_single_mapped::make_buffer, gr::host_buffer::make_buffer(), gr::buffer_double_mapped::make_buffer_double_mapped, and gr::host_buffer::make_host_buffer().

## ◆ mutex()

gr::thread::mutex * gr::buffer::mutex | ( |  | ) |
| inline

References d_mutex.

## ◆ nitems_written()

uint64_t gr::buffer::nitems_written | ( |  | ) |
| inline

References d_abs_write_offset.

## ◆ nreaders()

size_t gr::buffer::nreaders | ( |  | ) | const
| inline

References d_readers.

## ◆ on_lock()

void gr::buffer::on_lock | ( | gr::thread::scoped_lock & | lock | ) |
| overridevirtual

"on_lock" function from the custom_lock_if.

Implements gr::custom_lock_if.

## ◆ on_unlock()

void gr::buffer::on_unlock | ( |  | ) |
| overridevirtual

"on_unlock" function from the custom_lock_if.

Implements gr::custom_lock_if.

## ◆ output_blkd_cb_ready()

virtual bool gr::buffer::output_blkd_cb_ready | ( | int | output_multiple | ) |
| inlinevirtual

Returns true if the current thread is ready to execute output_blocked_callback(), false otherwise. Note if the default output_blocked_callback is overridden this function should also be overridden.

Reimplemented in gr::buffer_single_mapped.

## ◆ output_blocked_callback()

virtual bool gr::buffer::output_blocked_callback | ( | int | output_multiple,
|  | bool | force = false )
| inlinevirtual

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

Reimplemented in gr::buffer_single_mapped, and gr::host_buffer.

## ◆ post_work()

virtual void gr::buffer::post_work | ( | int | nitems | ) |
| pure virtual

Function to be executed after this object's owner completes the call to general_work().

Implemented in gr::buffer_double_mapped, and gr::host_buffer.

## ◆ prune_tags()

void gr::buffer::prune_tags | ( | uint64_t | max_time | ) |

Removes all tags before `max_time` from buffer.

Parameters

  max_time | the time (item number) to trim up until.

## ◆ reader()

buffer_reader * gr::buffer::reader | ( | size_t | index | ) |
| inline

References buffer_reader, and d_readers.

Referenced by drop_reader().

## ◆ remove_item_tag()

void gr::buffer::remove_item_tag | ( | const tag_t & | tag,
|  | long | id )

Removes an existing tag from the buffer.

If no such tag is found, does nothing. Note: Doesn't actually physically delete the tag, but marks it as deleted. For the user, this has the same effect: Any subsequent calls to get_tags_in_range() will not return the tag.

Parameters

  tag | the tag that needs to be removed
  id | the unique ID of the block calling this function

## ◆ reset_nitem_counter()

void gr::buffer::reset_nitem_counter | ( |  | ) |
| inline

References d_abs_write_offset, and d_write_index.

## ◆ set_done()

void gr::buffer::set_done | ( | bool | done | ) |

References done().

## ◆ set_transfer_type()

void gr::buffer::set_transfer_type | ( | const transfer_type & | type | ) |

Assign buffer's transfer_type.

## ◆ space_available()

virtual int gr::buffer::space_available | ( |  | ) |
| pure virtual

return number of items worth of space available for writing

Implemented in gr::buffer_double_mapped, and gr::buffer_single_mapped.

## ◆ update_reader_block_history()

virtual void gr::buffer::update_reader_block_history | ( | unsigned | history,
|  | int | delay )
| inlinevirtual

Reimplemented in gr::buffer_single_mapped.

References d_has_history, and d_max_reader_history.

## ◆ update_write_pointer()

void gr::buffer::update_write_pointer | ( | int | nitems | ) |

tell buffer that we wrote `nitems` into it

## ◆ write_pointer()

virtual void * gr::buffer::write_pointer | ( |  | ) |
| virtual

return pointer to write buffer.

The return value points at space that can hold at least space_available() items.

Reimplemented in gr::host_buffer.

## Friends And Related Symbol Documentation

## ◆ buffer_add_reader

GR_RUNTIME_API buffer_reader_sptr buffer_add_reader | ( | buffer_sptr | buf,
|  | int | nzero_preload,
|  | block_sptr | link = block_sptr(),
|  | int | delay = 0 )
| friend

Create a new gr::buffer_reader and attach it to buffer `buf`.

Parameters

  buf | is the buffer the `gr::buffer_reader` reads from.
  nzero_preload | – number of zero items to "preload" into buffer.
  link | is the block that reads from the buffer using this gr::buffer_reader.
  delay | Optional setting to declare the buffer's sample delay.

References GR_RUNTIME_API, and link().

## ◆ buffer_reader

friend class buffer_reader
| friend

References buffer_reader.

Referenced by buffer_reader, drop_reader(), and reader().

## ◆ buffer_reader_sm

friend class buffer_reader_sm
| friend

References buffer_reader_sm.

Referenced by buffer_reader_sm.

## ◆ make_buffer

GR_RUNTIME_API buffer_sptr make_buffer | ( | int | nitems,
|  | size_t | sizeof_item,
|  | uint64_t | downstream_lcm_nitems,
|  | block_sptr | link )
| friend

References GR_RUNTIME_API, and link().

## ◆ operator<<

std::ostream & operator<< | ( | std::ostream & | os,
|  | const buffer & | buf )
| friend

References buffer().

## Member Data Documentation

## ◆ d_abs_write_offset

uint64_t gr::buffer::d_abs_write_offset
| protected

Referenced by nitems_written(), and reset_nitem_counter().

## ◆ d_active_pointer_counter

uint32_t gr::buffer::d_active_pointer_counter
| protected

Referenced by decrement_active(), and increment_active().

## ◆ d_base

char* gr::buffer::d_base
| protected

Referenced by base().

## ◆ d_buf_map_type

buffer_mapping_type gr::buffer::d_buf_map_type
| protected

Referenced by get_mapping_type().

## ◆ d_bufsize

unsigned int gr::buffer::d_bufsize
| protected

Referenced by bufsize(), gr::buffer_double_mapped::index_add(), gr::buffer_single_mapped::index_add(), gr::buffer_double_mapped::index_sub(), and gr::buffer_single_mapped::index_sub().

## ◆ d_callback_flag

bool gr::buffer::d_callback_flag
| protected

Referenced by increment_active().

## ◆ d_cv

gr::thread::condition_variable gr::buffer::d_cv
| protected

Referenced by decrement_active(), and increment_active().

## ◆ d_debug_logger

gr::logger_ptr gr::buffer::d_debug_logger

## ◆ d_done

bool gr::buffer::d_done
| protected

Referenced by done().

## ◆ d_downstream_lcm_nitems

uint64_t gr::buffer::d_downstream_lcm_nitems
| protected

Referenced by get_downstream_lcm_nitems().

## ◆ d_has_history

bool gr::buffer::d_has_history
| protected

Referenced by update_reader_block_history().

## ◆ d_item_tags

std::multimap<uint64_t, tag_t> gr::buffer::d_item_tags
| protected

Referenced by get_tags_begin(), get_tags_end(), get_tags_lower_bound(), and get_tags_upper_bound().

## ◆ d_last_min_items_read

uint64_t gr::buffer::d_last_min_items_read
| protected

## ◆ d_link

std::weak_ptr<block> gr::buffer::d_link
| protected

Referenced by link().

## ◆ d_logger

gr::logger_ptr gr::buffer::d_logger

## ◆ d_max_reader_delay

unsigned gr::buffer::d_max_reader_delay
| protected

## ◆ d_max_reader_history

unsigned gr::buffer::d_max_reader_history
| protected

Referenced by update_reader_block_history().

## ◆ d_max_reader_output_multiple

uint32_t gr::buffer::d_max_reader_output_multiple
| protected

Referenced by get_max_reader_output_multiple().

## ◆ d_mutex

gr::thread::mutex gr::buffer::d_mutex
| protected

Referenced by decrement_active(), increment_active(), and mutex().

## ◆ d_readers

std::vector<buffer_reader*> gr::buffer::d_readers
| protected

Referenced by nreaders(), and reader().

## ◆ d_sizeof_item

size_t gr::buffer::d_sizeof_item
| protected

Referenced by get_sizeof_item().

## ◆ d_transfer_type

transfer_type gr::buffer::d_transfer_type
| protected

## ◆ d_write_index

unsigned int gr::buffer::d_write_index
| protected

Referenced by reset_nitem_counter().

## ◆ d_write_multiple

uint64_t gr::buffer::d_write_multiple
| protected

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

- buffer.h