Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members Related Pages

s3_pack_buffer Class Reference

An s3_pack_buffer one or more packed objects. More...

#include <s3_streamable.h>

List of all members.

Public Methods

s3_pack_buffer (size_t n_capacity=0)

Default and initialising constructor: construct a new instance of specified capacity. More...

s3_pack_buffer (void *n_buf, size_t n_size)

Initialising constructor: initialise from existing array. More...

~s3_pack_buffer ()

Destructor: deallocate the buffer if we own it. More...

void reset ()

Reset the current position to the beginning of the buffer, and set the size to zero. More...

const s3_pack_buffer & operator+= (int n) const

const operator+=(int). More...

s3_pack_buffer & operator+= (int n)

Increment the current position indicator by n bytes. More...

const void * get_buffer () const

const get_address(). More...

void * get_buffer ()

Return the address of the underlying buffer, i.e. More...

const void * get_current () const

const get_current(). More...

void * get_current ()

Return the address of the byte at the current position. More...

void set_capacity (size_t n)

Resize the buffer to the required size. More...

size_t get_size () const

Return the size of the buffer. More...

void copy_in (const void *src, size_t n)

Copy data from source buffer into the internal buffer, at the current position, and increment current position by n. More...

void copy_out (void *dst, size_t n) const

Copy data from the internal buffer, at the current position, and increment current position n. More...

Protected Methods

void enlarge (size_t n)

Enlarge the buffer to the specified size, copying all the data from the old buffer into the new one. More...

Protected Attributes

size_t capacity

Capacity: the number of bytes of currently allocated storage. More...

size_t pos

Current position. More...

unsigned char * buf

Pointer to buffer. More...

bool own_storage

Do we own the data ? More...

Detailed Description

An s3_pack_buffer one or more packed objects.

The packed data is represented internally as an array of unsigned char. A buffer has the following (abstract) attributes:

capacity: The maximum number of bytes that can be packed into the buffer. This is automatically increased if a packing operation would lead the buffer size to exceed the current capacity. It can also be explicitly set to a specified value.
size: The number of bytes that has been packed into a buffer. This can never exceed the capacity.
pos: The offset at which the next pack or unpack operation operates.

Methods to accomplish the following are provided:

Set the capacity.
Get the current size (the number of bytes copied into the buffer).
Get a pointer to the start of the packed data.
Get a pointer to the byte at the current position.
Increment the current position indicator by n bytes.
Copy n bytes into the buffer and increment the current position indicator by n.
Copy n bytes from the buffer and increment the current position indicator by n.

Calls to copy_in() and copy_out() should never be mixed. Don't break this rule, even if it seems to be working fine.

The underlying buffer is accessed through a pointer. An s3_pack_buffer may be created around an existing array of bytes, in which case the s3_pack_buffer does not own the underlying buffer, but is still able to traverse, read and modify it.

A const s3_pack_buffer only protects the data in the buffer against change, but allows the position to be changed (i.e. the constness reflects on the encapsulated data.

Definition at line 80 of file s3_streamable.h.

Constructor & Destructor Documentation

s3_pack_buffer::s3_pack_buffer ( size_t n_capacity = 0 )

Default and initialising constructor: construct a new instance of specified capacity.
The newly constructed instance owns the data and the following holds after construction:

capacity = n_capacity
size = 0
pos = 0

Parameters:

n_capacity (optional - default: 0)

Definition at line 30 of file s3_streamable.cc.
References buf, and capacity.

s3_pack_buffer::s3_pack_buffer ( void * n_buf,

size_t n_size

)

Initialising constructor: initialise from existing array.
This instance does not own the buffer. The capacity is set to be equal to n_size. The following holds after construction:

get_buffer() = n_buf
size = n_size
pos = 0

Parameters:

n_buf Address of first element in array.

n_size Size of array (number of unsigend char elements).

Definition at line 43 of file s3_streamable.cc.

s3_pack_buffer::~s3_pack_buffer ( )

Destructor: deallocate the buffer if we own it.

Definition at line 53 of file s3_streamable.cc.
References buf.

Member Function Documentation

void s3_pack_buffer::copy_in ( const void * src,

size_t n

)

Copy data from source buffer into the internal buffer, at the current position, and increment current position by n.

Parameters:

src Start of source buffer.

n Size of each element.

Definition at line 142 of file s3_streamable.cc.
References capacity, enlarge, get_current, and pos.
Referenced by s3_streamable_helper_pod::pack, s3_streamable_helper_pod::pack_array, and s3_streamable_helper_other< std::string >::pack.

void s3_pack_buffer::copy_out ( void * dst,

size_t n

) const

Copy data from the internal buffer, at the current position, and increment current position n.

Parameters:

dst Start address of destination.

n Number of elementd to copy.

Definition at line 154 of file s3_streamable.cc.
References capacity, CONST_OVERRIDE_THIS, get_current, and pos.
Referenced by s3_streamable_helper_pod::unpack, and s3_streamable_helper_pod::unpack_array.

void s3_pack_buffer::enlarge ( size_t n ) [protected]

Enlarge the buffer to the specified size, copying all the data from the old buffer into the new one.
The current position is unchanged. This fails with an abort() when it is invoked on an instance that does not own its storage. It is also very slow, as it performs a new - memcpy - delete sequence. Why do we have this ? It facicilitates interlacing of debugging strings with the packed data (without dicking with the pack sizes, which would result in such a mess that it would nullify any gains possibly achieved by debugging strings..
This is called by copy_in when S3_VERBOSE_PACKING is enabled (#defined) and the copy operation would overrrun the buffer.
Definition at line 170 of file s3_streamable.cc.
References buf, capacity, own_storage, and pos.
Referenced by copy_in, and operator+=.

void * s3_pack_buffer::get_buffer ( )

Return the address of the underlying buffer, i.e.
pointer to the first element.
Returns:
Address of buffer: buf.

Definition at line 94 of file s3_streamable.cc.
References buf.

const void * s3_pack_buffer::get_buffer ( ) const

const get_address().

Definition at line 88 of file s3_streamable.cc.
References CONST_OVERRIDE_THIS.
Referenced by s3_txport_tcp_rx_task::main_loop, and s3_txport_tcp_tx_task::main_loop.

void * s3_pack_buffer::get_current ( )

Return the address of the byte at the current position.

Returns:
Address of the byte at the current position: buf + pos.

Definition at line 106 of file s3_streamable.cc.
References buf, and pos.

const void * s3_pack_buffer::get_current ( ) const

const get_current().

Definition at line 100 of file s3_streamable.cc.
References CONST_OVERRIDE_THIS.
Referenced by copy_in, copy_out, and s3_streamable_helper_other< std::string >::unpack.

size_t s3_pack_buffer::get_size ( ) const

Return the size of the buffer.
The returned value is equal to pos, i.e. the number of bytes that has been copied into the buffer since the last reset().
Mixing calls to copy_in and copy_out would obviously screw this value up quite a bit, so don't mix these calls (2nd time I mention this).
Definition at line 136 of file s3_streamable.cc.
References pos.
Referenced by s3_txport_tcp_tx_task::main_loop.

s3_pack_buffer & s3_pack_buffer::operator+= ( int n )

Increment the current position indicator by n bytes.

Parameters:

n Number of bytes by which to increment the current position indicator (pos).

Returns:
*this

Definition at line 76 of file s3_streamable.cc.
References capacity, enlarge, and pos.

const s3_pack_buffer & s3_pack_buffer::operator+= ( int n ) const

const operator+=(int).

Definition at line 69 of file s3_streamable.cc.
References CONST_OVERRIDE_THIS.

void s3_pack_buffer::reset ( )

Reset the current position to the beginning of the buffer, and set the size to zero.
The capacity is unchanged. The following holds after this call returns:

size = 0
pos = 0

Definition at line 63 of file s3_streamable.cc.
References pos.
Referenced by s3_txport_tcp_rx_task::main_loop, and s3_txport_tcp_tx_task::main_loop.

void s3_pack_buffer::set_capacity ( size_t n )

Resize the buffer to the required size.
All the data present in the buffer at invocation is discarded, the size is set to zero and the position is set to the start of the buffer. The following holds after this call:

capacity = n
size = 0.
pos = 0 Note: The behaviour is only defined for instances of s3_pack_buffer that does own the underlying storage and should never be invoked on instances not meeting this requirement.

Parameters:

n New capacity.

Definition at line 112 of file s3_streamable.cc.
References buf, capacity, and pos.
Referenced by s3_txport_tcp_rx_task::main_loop.

Member Data Documentation

unsigned char* s3_pack_buffer::buf [protected]

Pointer to buffer.

Definition at line 99 of file s3_streamable.h.
Referenced by enlarge, get_buffer, get_current, s3_pack_buffer, set_capacity, and ~s3_pack_buffer.

size_t s3_pack_buffer::capacity [protected]

Capacity: the number of bytes of currently allocated storage.

Definition at line 86 of file s3_streamable.h.
Referenced by copy_in, copy_out, enlarge, operator+=, s3_pack_buffer, and set_capacity.

bool s3_pack_buffer::own_storage [protected]

Do we own the data ?

Definition at line 103 of file s3_streamable.h.
Referenced by enlarge.

size_t s3_pack_buffer::pos [protected]

Current position.

Definition at line 95 of file s3_streamable.h.
Referenced by copy_in, copy_out, enlarge, get_current, get_size, operator+=, reset, and set_capacity.

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

Send comments to: s3fc@stonethree.com

Public Methods
	s3_pack_buffer (size_t n_capacity=0)
	Default and initialising constructor: construct a new instance of specified capacity. More...
	s3_pack_buffer (void *n_buf, size_t n_size)
	Initialising constructor: initialise from existing array. More...
	~s3_pack_buffer ()
	Destructor: deallocate the buffer if we own it. More...
void	reset ()
	Reset the current position to the beginning of the buffer, and set the size to zero. More...
const s3_pack_buffer &	operator+= (int n) const
	`const` `operator+=(int)`. More...
s3_pack_buffer &	operator+= (int n)
	Increment the current position indicator by `n` bytes. More...
const void *	get_buffer () const
	`const` `get_address()`. More...
void *	get_buffer ()
	Return the address of the underlying buffer, i.e. More...
const void *	get_current () const
	`const` `get_current()`. More...
void *	get_current ()
	Return the address of the byte at the current position. More...
void	set_capacity (size_t n)
	Resize the buffer to the required size. More...
size_t	get_size () const
	Return the size of the buffer. More...
void	copy_in (const void *src, size_t n)
	Copy data from source buffer into the internal buffer, at the current position, and increment current position by `n`. More...
void	copy_out (void *dst, size_t n) const
	Copy data from the internal buffer, at the current position, and increment current position `n`. More...
Protected Methods
void	enlarge (size_t n)
	Enlarge the buffer to the specified size, copying all the data from the old buffer into the new one. More...
Protected Attributes
size_t	capacity
	Capacity: the number of bytes of currently allocated storage. More...
size_t	pos
	Current position. More...
unsigned char *	buf
	Pointer to buffer. More...
bool	own_storage
	Do we own the data ? More...