Ring buffer implementation for 8-bit bytes that's threadsafe and resizeable, and the methods are designed to be efficient in various ways, including by supporting the transfer of multiple bytes in variable quantities. More...

#include <rring>

Collaboration diagram for randolf::rring:

Public Member Functions
	rring (const size_t buffer_size)
	Instantiate an empty ring buffer (without automatic resizing-expansions).

	rring (const size_t buffer_size, const uint xp_max, const uint xp_play=2, const uint xp_block_size=0)
	Instantiate an empty ring buffer (with automatic resizing-expansion policies set so the internal buffer will be re-sized to adapt to unexpected allocation needs behind-the-scenes automatically).

	~rring () noexcept
	Free internal memory resources, after clearing buffer's memory (if the policy indicates that it needs to be cleared).

rring *	append (const char *data, int len=-1)
	Add any number of characters that fit within the unused portion of the internal ring buffer.

rring *	append (const char data)
	Add one character to the unused portion of the internal ring buffer.

rring *	append (const std::string data, int len=-1)
	Add any number of characters that fit within the unused portion of the internal ring buffer.

rring *	append (const std::vector< char > data, int len=-1)
	Add any number of characters that fit within the unused portion of the internal ring buffer.

rring *	append (const std::vector< unsigned char > data, int len=-1)
	Add any number of characters that fit within the unused portion of the internal ring buffer.

char	at (int index)
	Array-style access to the utilized portion of the ring buffer's contents, which yields the same result as that of the at() method.

char *	c_str (char *data=nullptr) noexcept
	Return the contents of the ring buffer as an ASCIIZ string.

randolf::rline *	copy_to_rline (int len=-1, randolf::rline *data=nullptr)
	Copy a line of text into a randolf::rline object. If an EoL sequence is not detected, the data will still fill the randolf::rline object.

char *	data (bool defragment_flag=true) noexcept
	Returns a pointer to the underlying ring buffer's array. If the "defragment" flag is cleared then the beginning of the array may not be the same as where the data actually begins (and ends) within the buffer (see the `warning` hereunder).

rring_bam *	data_bam (rring_bam *bam=nullptr) noexcept
	Returns the lengths and addresses of available memory. There may be only one block of memory, or two, depending on whether the available memory straddles the boundary of the ring buffer.

rring *	data_bam_adjust (size_t head, size_t tail=0)
	Arbitrarily change the head and tail positions in the ring buffer. This is intended for use in conjunction with appending data directly to the ring buffer after the data_bam method.

rring *	defragment (const bool full=true)
	Reorganizes the utilized memory in the ring buffer memory by moving the tail to the beginning. Defragmentation is completed in the most efficient manner, depending on what needs to be done. If data wraps around the buffer memory, then new memory will be allocated and data will be moved to it (old memory will also be cleared if the wipe policy is in effect).

size_t	discard (int len=-1) noexcept
	Discard data from the ring buffer.

bool	empty () noexcept
	Indicates whether the ring buffer is empty.

std::string	get_ascii_map (int len=65, const std::string u="\|", const std::string a=".") noexcept
	Obtains a one-line ASCII art depiction of a map of the ring buffer's memory usage, wherein the utilized and available portions are represented by the `\|` (pipe) and `.` (period) characters, respectively. These characters are configurable and may each contain more than one character, which is particularly useful for text-mode console output in a typical Linux shell in which `ANSI` or `AVATAR` codes may be used to present these characters or sequences in different colours, although there may be other uses for this too.

size_t	get_available () noexcept
	Calculate the number of available entries in the ring buffer.

size_t	get_base_size () noexcept
	Obtains the base size of the ring buffer, regardless of how much is utilized or available, and without any of the expansion policy limits.

size_t	get_head () noexcept
	Obtains the position of the head in the ring buffer.

size_t	get_max_size () noexcept
	Obtains the potential total size of the ring buffer, including both its utilized and available portions, including the maximum limit of what the expansion policies can extend the internal ring buffer's size to.

size_t	get_size () noexcept
	Obtains the total size of the current ring buffer, including both its utilized and available portions.

size_t	get_tail () noexcept
	Obtains the position of the tail in the ring buffer.

size_t	get_utilized () noexcept
	Calculate the number of utilized entries in the ring buffer.

bool	get_wipe_policy () noexcept
	Indicate whether internal buffer's memory will be cleared by the destructor before de-allocating it (default is `true` upon instantiation).

size_t	get_xp_block_size () noexcept
	Obtain block size in expansion policy.

size_t	get_xp_blocks_available () noexcept
	Obtain quantity of blocks available for use in buffer ring memory expansions.

size_t	get_xp_blocks_utilized () noexcept
	Obtain quantity of blocks utilized utilized for buffer ring memory expansion.

size_t	get_xp_max () noexcept
	Obtain maximum block quantity in expansion policy.

size_t	get_xp_play () noexcept
	Obtain minimum quantity of blocks available before automatic expansion block reduction policy.

	operator char * () noexcept
	Convert the entire contents of this ring buffer to an ASCIIZ string in the form of a `char*` array.

	operator std::string () noexcept
	Convert the entire contents of this ring buffer to an `std::string` object.

	operator std::vector< char > () noexcept
	Convert the entire contents of this ring buffer to an `std::vector<char>` object.

char	operator[] (int index)
	Array-style access to the utilized portion of the ring buffer's contents, which yields the same result as that of the at() method.

char	peek ()
	Duplicate a single character from the utilized portion of the internal ring buffer, and return it as an `char` primitive.

char *	peek_to_array (size_t len, char *data=nullptr)
	Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return them as a `char*` array.

std::string	peek_to_string (int len=-1, std::string data=std::string())
	Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return it as an `std::string` object.

std::vector< char >	peek_to_vector (int len=-1, std::vector< char > data=std::vector< char >())
	Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return it as an `std::string` object.

char	remove ()
	Remove one character from the utilized portion of the internal ring buffer, and return it .

char *	remove_to_array (size_t len, char *data=nullptr)
	Remove the specified number of characters from the utilized portion of the internal ring buffer, and return them as a `char*` array.

std::string	remove_to_string (int len=-1, std::string data=std::string())
	Remove the specified number of characters from the utilized portion of the internal ring buffer, and return it as an `std::string` object.

std::vector< char >	remove_to_vector (int len=-1, std::vector< char > data=std::vector< char >())
	Remove the specified number of characters from the utilized portion of the internal ring buffer, and return it as an `std::string` object.

rring *	reverse ()
	Flip the order of all entries in the ring buffer.

rring *	set_head (int offset, bool type=true)
	Alter the position of the internal head position, without changing any of the the pre-existing data in the underlying ring buffer.

rring *	set_size (const size_t len)
	Configure the total size of the ring buffer. The new size cannot be smaller than the amount of data that's already present in the ring buffer (see the get_utilized method to find out how much data is present).

rring *	set_tail (int offset, bool type=true)
	Alter the position of the internal tail position, without changing any of the the pre-existing data in the underlying ring buffer.

rring *	set_wipe_policy (const bool policy_flag) noexcept
	Specify whether the internal buffer's memory will be cleared by the destructor before de-allocating it (default is `true` upon instantiation).

rring *	set_xp_block_size (const uint xp_block_size)
	Configure the automatic expansion policy's incremental block size.

rring *	set_xp_max (const uint xp_max)
	Configure the automatic expansion policy's maximum number of blocks.

rring *	set_xp_play (const uint xp_play) noexcept
	Configure the automatic expansion policy's quantity of available blocks that must be present before attempting a reduction of ring buffer memory.

Friends
std::ostream &	operator<< (std::ostream &o, rring &c) noexcept
	Support convenient streaming usage with std::cout, std::cerr, and friends.

Detailed Description

Ring buffer implementation for 8-bit bytes that's threadsafe and resizeable, and the methods are designed to be efficient in various ways, including by supporting the transfer of multiple bytes in variable quantities.

Data is stored internally as a char* array, but a few methods are provided to also support easy interoperability with std::vector objects since there are many scenarios where this can be helpful (and from the perspective of optimization, this eliminates the cumbersome need to utilize conversions between std::string and std::vector objects since, internally, we use direct access to/from std::vector objects where needed).

Use case: Occasionally, ring buffers (a.k.a., circular buffers) are useful in specific situations because they provide better performance compared to other types of buffers, which either results in frequent allocations and deallocations of memory for transient-but-ordered portions of data or tracking sections of transient-but-ordered portions of data. A ring buffer relies on a single allocation of memory, along with a few variables for tracking top and bottom positions plus a few other internals to ensure smooth and accurate usage.

Expanding and reducing ring buffer memory automatically (which is disabled by default) is a feature that's particularly useful for server daemons that process small amounts of data most of the time. For example, an SMTP, IMAP4, POP3, MEOW, FTP, HTTP, FINGER, or WHOIS server that is rqeuired to minimize per-connection memory requirements can have a line buffer that begins with 80 characters, and be configured to increase to millions on-demand that will automatically shrink back down to the minimal 80 character buffer size, hence most of the time the buffer will only utilize 80 characters, with occasional longer lines that can be rejected efficiently or handled in some other way by the daemon without the complexity of memory management and, most importantly, without having to pre-allocate larger amounts of memory "just in case" a few connections start sending long lines (such as corrupt data, buffer overflow attempts that could be part of fuzzing tests or hacking efforts, etc.).

Conventions: Lower-case letters "rb" are regularly used in partial example code to represent an instantiated rring object.

An ASCIIZ string is a C-string (char* array) that includes a terminating null (0) character at the end.

History

2024-Nov-25 v1.00 Initial version
2024-Dec-03 v1.00 Added rring_bam structure integration
2024-Dec-03 v1.00 Added data_bam and related methods
2024-Dec-23 v1.00 Added defragment and reverse methods
2024-Dec-23 v1.00 Renamed peek_ methods to peek_to_ and remove_ methods to remove_to, so that the intention of these methods is more easily understood
2024-Dec-23 v1.00 Added internal methods to support ring buffer resizing
2024-Dec-24 v1.00 Added constructor that includes automatic expansion policy parameters
2024-Dec-25 v1.00 Implemented automatic buffer size expansion policies
2024-Dec-27 v1.00 Automatic buffer size expansion, reduction, and block resizing implementations are complete, and tested
2024-Jan-07 v1.00 Added copy_to_rline method
2024-Jan-09 v1.00 Added optional len parameter to various constructor, assign, and append methods for greater flexibility
2024-Jan-12 v1.00 Changed std::length_error to std::invalid_argument in response to length being specified as a negative value so this can more easily be handled with seperate code

Version: 1.00

Author: Randolf Richardson

Constructor & Destructor Documentation

◆ rring() [1/2]

randolf::rring::rring ( const size_t buffer_size )

inline

Instantiate an empty ring buffer (without automatic resizing-expansions).

Exceptions

std::bad_alloc If malloc() fails to allocate memory

Parameters

buffer_size Size of buffer

◆ rring() [2/2]

randolf::rring::rring	(	const size_t	buffer_size,
		const uint	xp_max,
		const uint	xp_play = 2,
		const uint	xp_block_size = 0 )

inline

Instantiate an empty ring buffer (with automatic resizing-expansion policies set so the internal buffer will be re-sized to adapt to unexpected allocation needs behind-the-scenes automatically).

Exceptions

std::bad_alloc If malloc() fails to allocate memory

Parameters

buffer_size	Size of buffer
xp_max	Maximum possible number of expansion blocks 0 = no expansions / effectively disabling expansion (default)
xp_play	Minimum number of available blocks before a reduction can occur
xp_block_size	Size of expansion blocks 0 = use `buffer_size` (default)

◆ ~rring()

randolf::rring::~rring ( )

inlinenoexcept

Free internal memory resources, after clearing buffer's memory (if the policy indicates that it needs to be cleared).

Member Function Documentation

◆ append() [1/5]

rring * randolf::rring::append ( const char data )

inline

Add one character to the unused portion of the internal ring buffer.

Exceptions

std::overflow_error If the amount of data exceeds the available free space in the ring buffer

Returns: The same rring object so as to facilitate stacking

See also: peek; remove

Parameters

data	Data to add

◆ append() [2/5]

rring * randolf::rring::append	(	const char *	data,
		int	len = -1 )

inline

Add any number of characters that fit within the unused portion of the internal ring buffer.

Exceptions

std::invalid_argument	If data length is -2 or below
std::overflow_error	If the amount of data exceeds the available free space in the ring buffer

Returns: The same rring object so as to facilitate stacking

See also: c_str; peek_to_array; remove_to_array

Parameters

data	Data to add
len	Length of data (-1 = treat `data` as an ASCIIZ string)

◆ append() [3/5]

rring * randolf::rring::append	(	const std::string	data,
		int	len = -1 )

inline

Add any number of characters that fit within the unused portion of the internal ring buffer.

Exceptions

std::invalid_argument	If data length is -2 or below
std::length_error	If data length is too long
std::overflow_error	If the amount of data exceeds the available free space in the ring buffer

Returns: The same rring object so as to facilitate stacking

See also: c_str; peek_to_string; remove_to_string

Parameters

data	Data to add
len	Length of data (-1 = rely on data.length())

◆ append() [4/5]

rring * randolf::rring::append	(	const std::vector< char >	data,
		int	len = -1 )

inline

Add any number of characters that fit within the unused portion of the internal ring buffer.

Exceptions

std::invalid_argument	If data length is -2 or below
std::overflow_error	If the amount of data exceeds the available free space in the ring buffer

Returns: The same rring object so as to facilitate stacking

See also: c_str; peek_to_vector; remove_to_vector

Parameters

data	Data to add
len	Length of data (-1 = treat `data` as an ASCIIZ string)

◆ append() [5/5]

rring * randolf::rring::append	(	const std::vector< unsigned char >	data,
		int	len = -1 )

inline

Add any number of characters that fit within the unused portion of the internal ring buffer.

Exceptions

std::invalid_argument	If data length is -2 or below
std::overflow_error	If the amount of data exceeds the available free space in the ring buffer

Returns: The same rring object so as to facilitate stacking

See also: c_str; peek_to_vector; remove_to_vector

Parameters

data	Data to add
len	Length of data (-1 = treat `data` as an ASCIIZ string)

◆ at()

char randolf::rring::at ( int index )

inline

Array-style access to the utilized portion of the ring buffer's contents, which yields the same result as that of the at() method.

The first element is at index 0.

Exceptions

std::out_of_range if the index is out-of-range

Returns: char

See also: operator[]

Parameters

index Index of character to access (0 = first element; negative index values are calculated in reverse, starting with -1 as the final position)

◆ c_str()

char * randolf::rring::c_str ( char * data = nullptr )

inlinenoexcept

Return the contents of the ring buffer as an ASCIIZ string.

Postcondition: The string returned will need to be free()'d after it's no longer needed.

#include <iostream>      // std::cout, std::cerr, std::endl, etc.
#include <randolf/rring>
 
int main(int argc, char *argv[]) {
  randolf::rring rb(1024);
  rb.append("This is an example.");
  char* c = rb.c_str();
  std::cout << "\"" << c << "\"" << std::endl;
  free(c);
  return EXIT_SUCCESS;
} // -x- int main -x-

Warning: When using the data parameter in a multi-threaded scenario, the amount of the memory needed should be set to the maximum size of this ring buffer to prevent unintended under-allocation resulting from a simultaneous increase in utilized ring buffer memory (caused by set_size).

Exceptions

std::bad_alloc If malloc() fails to allocate memory

Returns: ASCIIZ string

See also: append(const char*, int); append(const std::string, int); peek_to_array; peek_to_string

Parameters

data	Where to store the ASCIIZ string (including terminating zero, so it is imperative that `utilized() + 1` bytes be pre-allocated) `nullptr` = allocate the needed memory using `malloc()`

◆ copy_to_rline()

randolf::rline * randolf::rring::copy_to_rline	(	int	len = -1,
		randolf::rline *	data = nullptr )

inline

Copy a line of text into a randolf::rline object. If an EoL sequence is not detected, the data will still fill the randolf::rline object.

Note: If providing a pre-existing randolf::rline object, data will be appended to any existing data that's already present.

Exceptions

std::invalid_argument If len is less than -1

Returns: Data from ring buffer

See also: append(const std::string, int); c_str; peek; peek_to_array; peek_to_string; peek_to_vector

Parameters

len	Maximum quantity of data to duplicate -1 = all data
data	Pointer to an already-instantiated randolf::rline object to use nullptr = instantiate a new randolf::rline object (this will need to be `delete`'d when it's no longer needed)

◆ data()

char * randolf::rring::data ( bool defragment_flag = true )

inlinenoexceptADVANCED

Returns a pointer to the underlying ring buffer's array. If the "defragment" flag is cleared then the beginning of the array may not be the same as where the data actually begins (and ends) within the buffer (see the warning hereunder).

Warning: This is the live data, which should not be accessed or modified directly; use the data_bam() and data_bam_adjust() methods instead when there is a need to access or modify the backing array directly.

Exceptions

std::bad_alloc If malloc() fails to allocate memory (this can only occur when the "defragment" flag is set)

Returns: Pointer to buffer (not null terminated)

See also: data_bam; data_bam_adjust; defragment; get_available; get_utilized; set_size

Parameters

defragment_flag Whether to defragment the data first
TRUE = fuly defragment so that data begins at position 0 (default)
FALSE = don't defragment the data (this is an advanced feature that will require knowing how to use the data_bam method, and also the data_bam method if adding or removing data)

◆ data_bam()

rring_bam * randolf::rring::data_bam ( rring_bam * bam = nullptr )

inlinenoexceptADVANCED

Returns the lengths and addresses of available memory. There may be only one block of memory, or two, depending on whether the available memory straddles the boundary of the ring buffer.

This is the nearest equivalent of the data() methods provided in classes such as std::string and std::vector, but with the nuance of supporting the underpinnings of this ring buffer wherein the utilized portions may be stored at both the end and beginning of the buffer memory.

Note: The intention of this method is to provide an opportunity to directly update the contents of the ring buffer's data section in an efficient manner (e.g., such as by reading file or socket data directly into memory without having to perform separate data copying operations, etc.).

Warning: Upon updating a portion of the available-data block, the head will also need to be updated accordingly, for which the data_bam_adjust method is provided.

Exceptions

std::bad_alloc If malloc() fails to allocate memory

Returns: Pointer to rring_bam structure

See also: data; data_bam_adjust; empty; get_available; get_head; get_tail; get_utilized; rring_bam

Parameters

bam	Pointer to rring_bam structure (that's already been allocated) `nullptr` (default) = allocate memory for this structure with `malloc` (which will need to be `free`'d when it's no longer needed)

◆ data_bam_adjust()

rring * randolf::rring::data_bam_adjust	(	size_t	head,
		size_t	tail = 0 )

inlineADVANCED

Arbitrarily change the head and tail positions in the ring buffer. This is intended for use in conjunction with appending data directly to the ring buffer after the data_bam method.

Exceptions

std::overflow_error If either adjustment would result in causing an overflow

Returns: The same rring object so as to facilitate stacking

See also: data; data_bam; set_head; set_tail

Parameters

head	New internal head position
tail	New internal tail position

◆ defragment()

rring * randolf::rring::defragment ( const bool full = true )

inline

Reorganizes the utilized memory in the ring buffer memory by moving the tail to the beginning. Defragmentation is completed in the most efficient manner, depending on what needs to be done. If data wraps around the buffer memory, then new memory will be allocated and data will be moved to it (old memory will also be cleared if the wipe policy is in effect).

A full defragmentation always results in the tail changing to position 0.

Exceptions

std::length_error	If the new `buffer_size` is less than the total quantity of utilized entries (which would result in the truncation of data)
std::bad_alloc	If `malloc()` fails to allocate memory

Returns: The same rring object so as to facilitate stacking

See also: data; data_bam; get_ascii_map; get_wipe_policy; set_size

Parameters

full Whether to defrag when the utilized block isn't straddling the internal memory buffer boundary
TRUE = always fully defragment (default)
FALSE = only defragment if utilized block straddles memory boundary (this favours reducing processor overhead if all that's wanted is to have one block of memory to contend with in the BAM, hence it's also what the set_size() method uses for better performance overall because resizing most likely occurs when the need for CPU cycles are more critical, so we're doing our part by reducing our CPU load)

◆ discard()

size_t randolf::rring::discard ( int len = -1 )

inlinenoexcept

Discard data from the ring buffer.

Exceptions

std::invalid_argument If len is less than -1

Returns: Number of entries that were discarded

See also: remove

Parameters

len	Number of bytes to discard -1 = all utilized data that remains will be discarded (default)

◆ empty()

bool randolf::rring::empty ( )

inlinenoexcept

Indicates whether the ring buffer is empty.

Returns: TRUE = empty
FALSE = not empty

See also: data_bam; get_available; get_utilized; get_size

◆ get_ascii_map()

std::string randolf::rring::get_ascii_map	(	int	len = 65,
		const std::string	u = "\|",
		const std::string	a = "." )

inlinenoexcept

Obtains a one-line ASCII art depiction of a map of the ring buffer's memory usage, wherein the utilized and available portions are represented by the | (pipe) and . (period) characters, respectively. These characters are configurable and may each contain more than one character, which is particularly useful for text-mode console output in a typical Linux shell in which ANSI or AVATAR codes may be used to present these characters or sequences in different colours, although there may be other uses for this too.

Exceptions

std::invalid_argument If length is -2 or below

Returns: One-line ASCII depiction of ring buffer's memory map

See also: get_available; get_head; get_tail; get_utilized

Parameters

len	Desired size of ASCII map -1 = Use size of entire ring buffer
u	Character(s) representing utilized entries
a	Character(s) representing available entries

◆ get_available()

size_t randolf::rring::get_available ( )

inlinenoexcept

Calculate the number of available entries in the ring buffer.

Returns: Number of entries available

See also: data_bam; get_utilized; get_xp_blocks_available

◆ get_base_size()

size_t randolf::rring::get_base_size ( )

inlinenoexceptADVANCED

Obtains the base size of the ring buffer, regardless of how much is utilized or available, and without any of the expansion policy limits.

Returns: Maximum potential size of ring buffer

See also: empty; get_available; get_max_size; get_size; get_utilized; set_size

◆ get_head()

size_t randolf::rring::get_head ( )

inlinenoexceptADVANCED

Obtains the position of the head in the ring buffer.

Returns: Position of head in ring buffer

See also: data_bam; get_available; get_tail; get_utilized; set_head; set_tail

◆ get_max_size()

size_t randolf::rring::get_max_size ( )

inlinenoexceptADVANCED

Obtains the potential total size of the ring buffer, including both its utilized and available portions, including the maximum limit of what the expansion policies can extend the internal ring buffer's size to.

Returns: Maximum potential size of ring buffer

See also: empty; get_available; get_base_size; get_max_size; get_size; get_utilized; set_size

◆ get_size()

size_t randolf::rring::get_size ( )

inlinenoexceptADVANCED

Obtains the total size of the current ring buffer, including both its utilized and available portions.

Returns: Total current size of ring buffer

See also: empty; get_available; get_base_size; get_max_size; get_utilized; set_size

◆ get_tail()

size_t randolf::rring::get_tail ( )

inlinenoexceptADVANCED

Obtains the position of the tail in the ring buffer.

Returns: Position of tail in ring buffer

See also: data_bam; get_available; get_head; get_utilized; set_head; set_tail

◆ get_utilized()

size_t randolf::rring::get_utilized ( )

inlinenoexcept

Calculate the number of utilized entries in the ring buffer.

Returns: Number of entries utilized

See also: data_bam; get_available; get_xp_blocks_utilized

◆ get_wipe_policy()

bool randolf::rring::get_wipe_policy ( )

inlinenoexceptADVANCED

Indicate whether internal buffer's memory will be cleared by the destructor before de-allocating it (default is true upon instantiation).

Note: This is an important security feature for when the ring buffer may have been storing private data because it prevents the leaking of private data to other process that coincidentally gain access to the same memory area (e.g., by way of future calls to malloc()).

Returns: Post-wipe policy (TRUE = clear / FALSE = don't clear)

See also: set_wipe_policy

◆ get_xp_block_size()

size_t randolf::rring::get_xp_block_size ( )

inlinenoexceptADVANCED

Obtain block size in expansion policy.

Returns: Expansion policy's block size

See also: get_xp_max; get_xp_play; set_xp_block_size

◆ get_xp_blocks_available()

size_t randolf::rring::get_xp_blocks_available ( )

inlinenoexceptADVANCED

Obtain quantity of blocks available for use in buffer ring memory expansions.

Returns: Quantity of expansion blocks available

See also: get_available; get_xp_block_size; get_xp_blocks_utilized; get_xp_max; get_xp_play

◆ get_xp_blocks_utilized()

size_t randolf::rring::get_xp_blocks_utilized ( )

inlinenoexceptADVANCED

Obtain quantity of blocks utilized utilized for buffer ring memory expansion.

Returns: Quantity of expansion blocks utilized

See also: get_utilized; get_xp_block_size; get_xp_blocks_available; get_xp_max; get_xp_play

◆ get_xp_max()

size_t randolf::rring::get_xp_max ( )

inlinenoexceptADVANCED

Obtain maximum block quantity in expansion policy.

Returns: Expansion policy's maximum block quantity

See also: get_xp_block_size; get_xp_blocks_available; get_xp_blocks_utilized; get_xp_play; set_xp_max

◆ get_xp_play()

size_t randolf::rring::get_xp_play ( )

inlinenoexceptADVANCED

Obtain minimum quantity of blocks available before automatic expansion block reduction policy.

Returns: Expansion policy's play setting

See also: get_xp_block_size; get_xp_blocks_available; get_xp_blocks_utilized; get_xp_max; set_xp_play

◆ peek()

char randolf::rring::peek ( )

inline

Duplicate a single character from the utilized portion of the internal ring buffer, and return it as an char primitive.

Exceptions

std::overflow_error If the amount of data exceeds the amount of data in the ring buffer

Returns: Data from ring buffer

See also: append(const char); c_str; peek_to_array; peek_to_string; peek_to_vector; remove

◆ peek_to_array()

char * randolf::rring::peek_to_array	(	size_t	len,
		char *	data = nullptr )

inline

Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return them as a char* array.

Postcondition: The string returned will need to be free()'d after it's no longer needed.

Exceptions

std::bad_alloc	If `malloc()` fails to allocate memory
std::overflow_error	If the amount of data exceeds the amount of data in the ring buffer

Returns: Data from ring buffer

See also: append(const char*, int); c_str; peek; peek_to_string; peek_to_vector; remove_to_array

Parameters

len	Amount of data to duplicate
data	Where to store the data `nullptr` = allocate the needed memory using `malloc()`

◆ peek_to_string()

std::string randolf::rring::peek_to_string	(	int	len = -1,
		std::string	data = std::string() )

inline

Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string object.

Exceptions

std::invalid_argument	If data length is -2 or below
std::overflow_error	If the amount of data exceeds the amount of data in the ring buffer

Returns: Data from ring buffer

See also: append(const std::string, int); c_str; peek; peek_to_array; peek_to_vector; remove_to_string

Parameters

len	Amount of data to duplicate -1 = all data
data	The previously instantiated std::string object to use (the default is to instantiate a new instance of std::string).

◆ peek_to_vector()

std::vector< char > randolf::rring::peek_to_vector	(	int	len = -1,
		std::vector< char >	data = std::vector<char>() )

inline

Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string object.

Exceptions

std::invalid_argument	If data length is -2 or below
std::overflow_error	If the amount of data exceeds the amount of data in the ring buffer

Returns: Data from ring buffer

See also: append(const std::vector<char>, int); append(const std::vector<unsigned char>, int); c_str; peek; peek_to_array; peek_to_string; remove_to_vector

Parameters

len	Amount of data to duplicate -1 = all data
data	The previously instantiated std::string object to use (the default is to instantiate a new instance of std::string).

◆ remove()

char randolf::rring::remove ( )

inline

Remove one character from the utilized portion of the internal ring buffer, and return it .

Exceptions

std::overflow_error If the amount of data exceeds the amount of data in the ring buffer

Returns: Data from ring buffer

See also: append(const char); c_str; peek; remove_to_array; remove_to_string; remove_to_vector

◆ remove_to_array()

char * randolf::rring::remove_to_array	(	size_t	len,
		char *	data = nullptr )

inline

Remove the specified number of characters from the utilized portion of the internal ring buffer, and return them as a char* array.

Postcondition: The string returned will need to be free()'d after it's no longer needed.

Exceptions

std::bad_alloc	If `malloc()` fails to allocate memory
std::overflow_error	If the amount of data exceeds the amount of data in the ring buffer

Returns: Data from ring buffer

See also: append(const char*, int); c_str; peek_to_array; remove; remove_to_string; remove_to_vector

Parameters

len	Maximum quantity of data to move
data	Where to store the data `nullptr` = allocate the needed memory using `malloc()`

◆ remove_to_string()

std::string randolf::rring::remove_to_string	(	int	len = -1,
		std::string	data = std::string() )

inline

Remove the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string object.

Exceptions

std::invalid_argument	If data length is -2 or below
std::overflow_error	If the amount of data exceeds the amount of data in the ring buffer

Returns: Data from ring buffer

See also: append(const std::string, int); c_str; peek_to_string; remove; remove_to_array; remove_to_vector

Parameters

len	Amount of data to remove -1 = all data
data	The previously instantiated std::string object to use (the default is to instantiate a new instance of std::string).

◆ remove_to_vector()

std::vector< char > randolf::rring::remove_to_vector	(	int	len = -1,
		std::vector< char >	data = std::vector<char>() )

inline

Remove the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string object.

Exceptions

std::invalid_argument	If data length is -2 or below
std::overflow_error	If the amount of data exceeds the amount of data in the ring buffer

Returns: Data from ring buffer

See also: append(const std::vector<char>, int); append(const std::vector<unsigned char>, int); c_str; peek_to_vector; remove; remove_to_array; remove_to_string

Parameters

len	Amount of data to remove -1 = all data
data	The previously instantiated std::string object to use (the default is to instantiate a new instance of std::string).

◆ reverse()

rring * randolf::rring::reverse ( )

inline

Flip the order of all entries in the ring buffer.

Returns: The same rring object so as to facilitate stacking

◆ set_head()

rring * randolf::rring::set_head	(	int	offset,
		bool	type = true )

inlineADVANCED

Alter the position of the internal head position, without changing any of the the pre-existing data in the underlying ring buffer.

Exceptions

std::overflow_error If the new position falls beyond the internal tail position (or, in other words, it exceeds the available free space in the ring buffer)

Returns: The same rring object so as to facilitate stacking

See also: get_available; get_head; get_tail; get_utilized; set_tail

Parameters

offset	Position adjustment (may also be negative, but only for relative `type`)
type	Type of adjustment TRUE = absolute (default) FALSE = relative (`offset` may also be negative)

◆ set_size()

rring * randolf::rring::set_size ( const size_t len )

inline

Configure the total size of the ring buffer. The new size cannot be smaller than the amount of data that's already present in the ring buffer (see the get_utilized method to find out how much data is present).

Exceptions

std::overflow_error If the new size exceeds the amount of data that's already present in the ring buffer

Returns: The same rring object so as to facilitate stacking

See also: get_available; get_size; get_utilized

Parameters

len	New size of ring buffer

◆ set_tail()

rring * randolf::rring::set_tail	(	int	offset,
		bool	type = true )

inlineADVANCED

Alter the position of the internal tail position, without changing any of the the pre-existing data in the underlying ring buffer.

Exceptions

std::overflow_error If the new position falls beyond the internal head position (or, in other words, it exceeds the available free space in the ring buffer)

Returns: The same rring object so as to facilitate stacking

See also: get_available; get_head; get_tail; get_utilized; set_head

Parameters

offset	Position adjustment (may also be negative, but only for relative `type`)
type	Type of adjustment TRUE = absolute (default) FALSE = relative (`offset` may also be negative)

◆ set_wipe_policy()

rring * randolf::rring::set_wipe_policy ( const bool policy_flag )

inlinenoexceptADVANCED

Specify whether the internal buffer's memory will be cleared by the destructor before de-allocating it (default is true upon instantiation).

Note: This is an important security feature for when the ring buffer may have been storing private data because it prevents the leaking of private data to other process that coincidentally gain access to the same memory area (e.g., by way of future calls to malloc()).

Returns: The same rring object so as to facilitate stacking

See also: get_wipe_policy

Parameters

policy_flag TRUE = clear buffer memory in destructor
FALSE = don't clear buffer memory in destructor

◆ set_xp_block_size()

rring * randolf::rring::set_xp_block_size ( const uint xp_block_size )

inlineADVANCED

Configure the automatic expansion policy's incremental block size.

Exceptions

std::overflow_error If the new setting, which reduces the maximum quantity of blocks, exceeds the available memory and would otherwise result in losing some of the utilized entries

Returns: The same rring object so as to facilitate stacking

See also: get_xp_block_size; set_xp_max; set_xp_play

Parameters

xp_block_size Maximum possible number of expansion blocks
0 = disable expansion policy

◆ set_xp_max()

rring * randolf::rring::set_xp_max ( const uint xp_max )

inlineADVANCED

Configure the automatic expansion policy's maximum number of blocks.

Exceptions

std::overflow_error If the new setting, which reduces the maximum quantity of blocks, exceeds the available memory and would otherwise result in losing some of the utilized entries

Returns: The same rring object so as to facilitate stacking

See also: get_xp_max; set_xp_block_size; set_xp_play

Parameters

xp_max Maximum possible number of expansion blocks
0 = disable expansion policy

◆ set_xp_play()

rring * randolf::rring::set_xp_play ( const uint xp_play )

inlinenoexceptADVANCED

Configure the automatic expansion policy's quantity of available blocks that must be present before attempting a reduction of ring buffer memory.

Returns: The same rring object so as to facilitate stacking

See also: get_xp_play; set_xp_block_size; set_xp_max

Parameters

xp_play Number of available blocks must be present before attempting reduction

◆ operator char *()

randolf::rring::operator char * ( )

inlinenoexcept

Convert the entire contents of this ring buffer to an ASCIIZ string in the form of a char* array.

Postcondition: The string returned will need to be free()'d after it's no longer needed.

#include <iostream>      // std::cout, std::cerr, std::endl, etc.
#include <randolf/rring>
 
int main(int argc, char *argv[]) {
  randolf::rring rb(1024);
  rb.append("This is an example.");
  char* c = rb;
  std::cout << "\"" << c << "\"" << std::endl;
  free(c);
  return EXIT_SUCCESS;
} // -x- int main -x-

Exceptions

std::bad_alloc If malloc() fails to allocate memory

Returns: Contents of this ring buffer as an ASCII string as a char* array.

See also: c_str

◆ operator std::string()

randolf::rring::operator std::string ( )

inlinenoexcept

Convert the entire contents of this ring buffer to an std::string object.

#include <iostream>      // std::cout, std::cerr, std::endl, etc.
#include <string>        // std::string
#include <randolf/rring>
 
int main(int argc, char *argv[]) {
  randolf::rring rb(1024);
  rb.append("This is an example.");
  std::string s = rb;
  std::cout << "\"" << s << "\"" << std::endl;
  return EXIT_SUCCESS;
} // -x- int main -x-

Returns: Contents of this ring buffer as an std::string object

See also: peek_to_string

◆ operator std::vector< char >()

randolf::rring::operator std::vector< char > ( )

inlinenoexcept

Convert the entire contents of this ring buffer to an std::vector<char> object.

#include <iostream>      // std::cout, std::cerr, std::endl, etc.
#include <string>        // std::string
#include <vector>        // std::vector
#include <randolf/rring>
 
int main(int argc, char *argv[]) {
  randolf::rring rb(1024);
  rb.append("This is an example.");
  std::vector<char> v = rb;
  std::cout << "\"" << std::string(v.begin(), v.end()) << "\"" << std::endl;
  return EXIT_SUCCESS;
} // -x- int main -x-

Returns: Contents of this ring buffer as an std::vector<char> object

See also: peek_to_vector

◆ operator[]()

char randolf::rring::operator[] ( int index )

inline

Array-style access to the utilized portion of the ring buffer's contents, which yields the same result as that of the at() method.

The first element is at index 0.

Exceptions

std::out_of_range if the index is out-of-range

Returns: char

See also: at

Parameters

index Index of character to access (0 = first element; negative index values are calculated in reverse, starting with -1 as the final position)

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	o,
		rring &	c )

friend

Support convenient streaming usage with std::cout, std::cerr, and friends.

#include <iostream>      // std::cout, std::cerr, std::endl, etc.
#include <string>        // std::string
#include <randolf/rring>
 
int main(int argc, char *argv[]) {
  randolf::rring rb(1024);
  rb.append("This is an example.");
  std::cout << "\"" << rb << "\"" << std::endl;
  return EXIT_SUCCESS;
} // -x- int main -x-

Returns: Contents of this ring buffer as an std::string object (which will be de-allocated by the std::string object's destructor upon going out of scope)

See also: peek_to_string

Parameters

o	Output stream (provided automatically by std::cout and std::cerr)
c	Object class (matched by compiler)

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

randolf/rring

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ rring() [1/2]

◆ rring() [2/2]

◆ ~rring()

Member Function Documentation

◆ append() [1/5]

◆ append() [2/5]

◆ append() [3/5]

◆ append() [4/5]

◆ append() [5/5]

◆ at()

◆ c_str()

◆ copy_to_rline()

◆ data()

◆ data_bam()

◆ data_bam_adjust()

◆ defragment()

◆ discard()

◆ empty()

◆ get_ascii_map()

◆ get_available()

◆ get_base_size()

◆ get_head()

◆ get_max_size()

◆ get_size()

◆ get_tail()

◆ get_utilized()

◆ get_wipe_policy()

◆ get_xp_block_size()

◆ get_xp_blocks_available()

◆ get_xp_blocks_utilized()

◆ get_xp_max()

◆ get_xp_play()

◆ peek()

◆ peek_to_array()

◆ peek_to_string()

◆ peek_to_vector()

◆ remove()

◆ remove_to_array()

◆ remove_to_string()

◆ remove_to_vector()

◆ reverse()

◆ set_head()

◆ set_size()

◆ set_tail()

◆ set_wipe_policy()

◆ set_xp_block_size()

◆ set_xp_max()

◆ set_xp_play()

◆ operator char *()

◆ operator std::string()

◆ operator std::vector< char >()

◆ operator[]()

Friends And Related Symbol Documentation

◆ operator<<