Private implementation of the reference counted data object used to wrap datablocks. More...

#include <IrisBuffer.hpp>

Public Member Functions
	__INTERNAL__Buffer (BufferReferenceStrength) noexcept

	__INTERNAL__Buffer (BufferReferenceStrength, size_t capacity) noexcept

	__INTERNAL__Buffer (BufferReferenceStrength, const void *const data, size_t bytes) noexcept

	__INTERNAL__Buffer (const __INTERNAL__Buffer &)=delete

__INTERNAL__Buffer &	operator= (const __INTERNAL__Buffer &)=delete

	operator void *const () const
	Returns pointer to the beginning of the underlying data block.

	operator bool () const
	Operator to see if the buffer reference is valid.

BufferReferenceStrength	get_strength () const
	Get the reference strength to the underlying data wrapped by the buffer.

Result	change_strength (BufferReferenceStrength strength_to_assign)
	Change the strength of the underlying reference.

void *	data () const
	Returns pointer to the beginning of the underlying data block.

void *	end () const
	Returns a pointer to the next unwritten location in the buffer.

Result	prepare (size_t amount_of_bytes_to_prepare)
	Extends the capacity of the buffer without affecting the size.

void *	append (size_t append_by_bytes)
	Expands the size of the buffer without writing data into the expanded space.

Result	append (void *data, size_t size)
	Appends the end of the buffer by copying data into the buffer.

size_t	size () const
	Returns the current size of the buffer.

Result	set_size (size_t buffer_valid_size_bytes)
	Set the size object.

size_t	capacity () const
	Returns the total capacity of the buffer (used and unused)

size_t	available_bytes () const
	Returns the remaining bytes within the buffer that are unused.

Result	resize (size_t expected_size_bytes)
	Resize the underlying datablock.

Result	shrink_to_fit ()
	Shrinks the underlying data block to fit the used space.

Detailed Description

Private implementation of the reference counted data object used to wrap datablocks.

It can either strong reference or weak reference the underlying data. The buffer can also shift between weak and strong referrences if chosen; however, this is very dangerous obviously and you need to ensure you are tracking if you have switched from weak to strong or vice versa.

Warning: Use of the __INTERNAL__Buffer is given as a courtesy for developers who want greater efficiency and control over datablocks. These methods were created for the internal use by Iris Developers and come with some inherant risk.; __INTERNAL__Buffer is currently NOT thread safe. This will be fixed in future updates.

Member Function Documentation

◆ append() [1/2]

void * Iris::__INTERNAL__Buffer::append ( size_t append_by_bytes )

Expands the size of the buffer without writing data into the expanded space.

This expands the buffer size without actually writing any data into the new buffer space. This is useful for streaming data where you may be aware of the size of incoming data but need a space for that data (off the network card) to be copied. If this expansion goes beyond available_bytes(), the data-block will be expanded similarly to prepare(size_t).

See also: prepare(size_t), available_bytes()

Warning: this may invalidate any prior reference to the data() pointer. Any local variables that reference the data within this buffer may become immediately invalid. You may check if resize changed the buffer by evaluating a comparison between data() before calling and data() after calling.

Parameters

append_by_bytes the number of bytes by which to expand the buffer

Returns: void* to the beginning of writable space where new data should be added.

◆ append() [2/2]

Result Iris::__INTERNAL__Buffer::append	(	void *	data,
		size_t	size )

Appends the end of the buffer by copying data into the buffer.

This works similarly to append(size_t) but performs a copy transaction, copying the C-style array into the end of the current block.

Warning: this may invalidate any prior reference to the data() pointer. Any local variables that reference the data within this buffer may become immediately invalid. You may check if resize changed the buffer by evaluating a comparison between data() before calling and data() after calling.

Parameters

data	C-style pointer to data array
size	Size of data in bytes

Returns: IRIS_SUCCESS on successful appending of data to end of buffer

◆ available_bytes()

size_t Iris::__INTERNAL__Buffer::available_bytes ( ) const

Returns the remaining bytes within the buffer that are unused.

This value is equivalent to capacity() - size().

Returns: size_t unused bytes in the current data block

◆ capacity()

size_t Iris::__INTERNAL__Buffer::capacity ( ) const

Returns the total capacity of the buffer (used and unused)

Returns: size_t capacity in bytes; IRIS_SUCCESS on successfully changing the internal size tracker; IRIS_FAILURE type on failure to change the tracker

◆ change_strength()

Result Iris::__INTERNAL__Buffer::change_strength ( BufferReferenceStrength strength_to_assign )

Change the strength of the underlying reference.

If switching to STRONG reference, this buffer will become responsible for the freeing of the underlying data. Whatever mallocated the data is NO LONGER RESPONSIBLE for FREEING the underlying data. If switched to WEAK reference, the buffer will give up the responsibility to free the data and it now becomes the responsibility of the program to avoid a memory leak.

Parameters

strength_to_assign REFERENCE_WEAK or REFERENCE_STRONG

◆ data()

void * Iris::__INTERNAL__Buffer::data ( ) const

Returns pointer to the beginning of the underlying data block.

This returns a pointer to the start of the datablock, not the start of unwritten data. If you wish to write into the buffer, use prepare() or append().

See also: end(), prepare(), and append()

Returns: void* a pointer to the start of the internal data wrapped by the buffer.

◆ end()

void * Iris::__INTERNAL__Buffer::end ( ) const

Returns a pointer to the next unwritten location in the buffer.

This has no effect on the size of the buffer. If the buffer needs to be resized use the append(size_t) method to expand the buffer.

See also: append_(size_t)

Note: If this extends beyond the capacity, a nullptr is returned.

Returns: void* that points to the next unwritten byte in the buffer.

◆ get_strength()

BufferReferenceStrength Iris::__INTERNAL__Buffer::get_strength ( ) const

Get the reference strength to the underlying data wrapped by the buffer.

Returns: REFERENCE_WEAK if the buffer only references the data and does not own it; REFERENCE_STRONG if the buffer owns the data and controls the data lifetime

◆ operator bool()

Iris::__INTERNAL__Buffer::operator bool ( ) const

Operator to see if the buffer reference is valid.

Returns: true if a valid data block backs this buffer; false if there is no valid data block backing this buffer

◆ operator void *const()

Iris::__INTERNAL__Buffer::operator void *const ( ) const

Returns pointer to the beginning of the underlying data block.

Returns: void* const

◆ prepare()

Result Iris::__INTERNAL__Buffer::prepare ( size_t amount_of_bytes_to_prepare )

Extends the capacity of the buffer without affecting the size.

This extends the amount of data that the buffer can hold and may lead to a resizing of the data block backing the buffer but without actually expanding the size of the committed data. This is useful if you know how much data to expect but do not have that data yet. If you wish to expand the size as well, see append().

See also: append()

Warning: this may invalidate any prior reference to the data() pointer. Any local variables that reference the data within this buffer may become immediately invalid. You may check if resize changed the buffer by evaluating a comparison between data() before calling and data() after calling.

Parameters

amount_of_bytes_to_prepare the number of bytes by which to expand the buffer

Returns: IRIS_SUCCESS on successful extension of buffer capacity

◆ resize()

Result Iris::__INTERNAL__Buffer::resize ( size_t expected_size_bytes )

Resize the underlying datablock.

This is fundamentally different from calling set_size(size_t) as it actually changes the size of the backing data block by the kernel. Calling this method can invalidate the underlying data pointer.

Note: You should use prepare()

Warning: this may invalidate any prior reference to the data() pointer. Any local variables that reference the data within this buffer may become immediately invalid. You may check if resize changed the buffer by evaluating a comparison between data() before calling and data() after calling.

Parameters

expected_size_bytes

Returns: IRIS_SUCCESS on successfully resizing the buffer object

◆ set_size()

Result Iris::__INTERNAL__Buffer::set_size ( size_t buffer_valid_size_bytes )

Set the size object.

Assign the internal size of the complete buffer to the given size in bytes. If you are simply adding some number of bytes to the buffer, use append(size) instead.

Note: This is an unsafe method and generally should not be used without a really good reason.

Warning: If the argument is less than the current buffer size, this will cut that data to the given size. Unlike resize, the data will still persist but will be overwritten with the next call of append.

Parameters

buffer_valid_size_bytes size in bytes to set the buffer's internal tracker

Returns: Result

◆ shrink_to_fit()

Result Iris::__INTERNAL__Buffer::shrink_to_fit ( )

Shrinks the underlying data block to fit the used space.

This is equivalent to calling resize(size()). This will not invalidate any pointers and is generally a safe way to reduce space consumption by buffers.

Returns: IRIS_SUCCESS on successfully resizing the buffer object

◆ size()

size_t Iris::__INTERNAL__Buffer::size ( ) const

Returns the current size of the buffer.

This is distinct from the buffer capacity

See also: capacity()

Returns: size_t number of bytes written to the buffer.

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

src/IrisBuffer.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ append() [1/2]

◆ append() [2/2]

◆ available_bytes()

◆ capacity()

◆ change_strength()

◆ data()

◆ end()

◆ get_strength()

◆ operator bool()

◆ operator void *const()

◆ prepare()

◆ resize()

◆ set_size()

◆ shrink_to_fit()

◆ size()