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

inline protected virtual

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 )

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

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

inline virtual

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 )

inline virtual

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

override virtual

"on_lock" function from the custom_lock_if.

Implements gr::custom_lock_if.

## on_unlock()

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

override virtual

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

inline virtual

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 )

inline virtual

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 )

inline virtual

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