buffer Class Reference

A buffer is a blob of memory broken into pieces that we call "packets". More...

#include <buffer.h>

Inheritance diagram for buffer:

[legend]Collaboration diagram for buffer:


Public Member Functions
	buffer (const buffer_key &key, byte_array &contents, int packet_size)
	creates a buffer containing the "contents" specified.
	buffer (const buffer_key &key, int total_packets, int maximum_packet)
	creates a buffer for filling at a later time.
	buffer (const buffer_key &key, const buffer_base &to_copy)
	makes this buffer become a copy of "to_copy".
virtual	~buffer ()
	releases any storage used by the buffer.
	IMPLEMENT_CLASS_NAME ("buffer")
virtual bool	alive () const
	returns true if this buffer is still alive.
virtual int	packets () const
	the number of packets in this buffer.
virtual buffer_key	key () const
	observe the key for this buffer.
virtual void	set_key (const buffer_key &to_set)
	observe or modify the key for this buffer.
virtual outcome	store_packet (int packet_number, const byte_array &buffer)
	puts a packet into the buffer at the "packet_number"th position.
virtual byte_array	get_packet (int packet_number) const
	returns a packet from the buffer.
virtual int	packet_length (int packet_number) const
	returns the length of a particular packet.
virtual bool	whole () const
	returns true if the entire buffer has been stored.
virtual bool	empty () const
	returns true if the buffer has no packets stored yet.
virtual int	full_length (int offset=0) const
	returns the full length of this buffer, ignoring first "offset" bytes.
virtual int	guess_size (int offset=0)
	provides an estimate of what the full size will eventually be.
virtual bool	did_estimate () const
	returns true if we have previously estimated a size for this buffer.
virtual void	reset_estimate ()
	tosses our earlier estimate of the buffer's size.
virtual int	estimate () const
	returns our estimate, if we've made one.
virtual outcome	dump (byte_array &storage_location, int offset=0)
	stuffs the entire buffer into contiguous memory at "storage_location".
virtual void	release (int packet_number, release_style status_handling=KEEP_STATUS)
	frees the storage for the "packet_number"th packet.
virtual void	release ()
	frees the entire buffer, returning it to an unallocated state.
virtual istring	text_form () const
	returns a text string representing the state of the buffer.
virtual istring	detailed_form (bool really_detailed=false) const
	returns a more detailed text string for this buffer.
virtual time_stamp	last_add () const
	the last time that the buffer was updated.
virtual void	set_last_add (const time_stamp &new_last_add)
	sets the last buffer update time to the "new_last_add".
virtual bool	owner_alerted () const
	true if the buffer owner was told that this buffer is ready.
virtual void	set_alerted (bool owner_alerted)
	records "owner_alerted" as the new state for the owner.
virtual void	get_attachment (byte_array &storage) const
	retrieves any extra attached data that was hanging on the buffer.
virtual void	set_attachment (const byte_array &new_attachment)
	sets "new_attachment" to dangle from the buffer.
virtual span_manager	buffer_status () const
	tells which packets in the buffer are available.
virtual int_array	packet_sizes () const
	returns the sizes of each packet in the buffer, if known.
int	references () const
	returns the number of other buffers linked to this one.
int_set	get_references () const
	returns all the connection ids that are linked to this one.
void	add_reference (int conn_id)
	adds a new reference to this buffer for the connection "conn_id".
void	remove_reference (int conn_id)
	zaps a reference to this buffer for the connection "conn_id".

Detailed Description

A buffer is a blob of memory broken into pieces that we call "packets".

Buffers can be constructed from existing memory or they can be set up for packets that are expected to arrive later on.

Definition at line 31 of file buffer.h.

Constructor & Destructor Documentation

buffer::buffer	(	const buffer_key &	key,
		byte_array &	contents,
		int	packet_size
	)

creates a buffer containing the "contents" specified.

the "packet_size" is how large each unit of the buffer should be. after the buffer is added, "contents" is empty, having been drained efficiently.

Definition at line 41 of file buffer.cpp.

References array< contents >::access(), last_packet_size(), array< contents >::length(), array< contents >::snarf(), and span_manager::update().

Referenced by store_packet().

buffer::buffer	(	const buffer_key &	key,
		int	total_packets,
		int	maximum_packet
	)

creates a buffer for filling at a later time.

the buffer is only told the number of total packets in the message. the full length will be determined later by piecing together the individual packets when the message is ready. this uses the "maximum_packet" to guess the eventual size for purposes of memory usage estimation.

Definition at line 81 of file buffer.cpp.

buffer::buffer	(	const buffer_key &	key,
		const buffer_base &	to_copy
	)

makes this buffer become a copy of "to_copy".

"to_copy" must be done accumulating data for this to work.

buffer::~buffer ( ) [virtual]

releases any storage used by the buffer.

Definition at line 97 of file buffer.cpp.

References release(), and WHACK().

Member Function Documentation

buffer::IMPLEMENT_CLASS_NAME ( "buffer" )

bool buffer::alive ( ) const [virtual]

returns true if this buffer is still alive.

Implements buffer_base.

Definition at line 116 of file buffer.cpp.

Referenced by linked_buffer::alive().

int buffer::packets ( ) const [virtual]

the number of packets in this buffer.

Implements buffer_base.

Definition at line 156 of file buffer.cpp.

Referenced by detailed_form(), and linked_buffer::packets().

buffer_key buffer::key ( ) const [virtual]

observe the key for this buffer.

Implements buffer_base.

Definition at line 144 of file buffer.cpp.

void buffer::set_key ( const buffer_key & to_set ) [virtual]

observe or modify the key for this buffer.

Implements buffer_base.

Definition at line 147 of file buffer.cpp.

outcome buffer::store_packet	(	int	packet_number,
		const byte_array &	buffer
	)			`[virtual]`

puts a packet into the buffer at the "packet_number"th position.

if the packet has already been stored previously, then IN_USE is returned.

Implements buffer_base.

Definition at line 237 of file buffer.cpp.

References buffer_base::BAD_INPUT, bounds_return, buffer(), FUNCDEF, buffer_base::IN_USE, bit_vector::light(), buffer_base::OKAY, bit_vector::on(), time_stamp::reset(), and span_manager::vector().

Referenced by linked_buffer::store_packet().

byte_array buffer::get_packet ( int packet_number ) const [virtual]

returns a packet from the buffer.

if that packet has not been stored yet, then NIL is returned.

Implements buffer_base.

Definition at line 253 of file buffer.cpp.

References bounds_return, and FUNCDEF.

Referenced by linked_buffer::get_packet().

int buffer::packet_length ( int packet_number ) const [virtual]

returns the length of a particular packet.

Implements buffer_base.

Definition at line 262 of file buffer.cpp.

References bounds_return, and FUNCDEF.

Referenced by linked_buffer::packet_length().

bool buffer::whole ( ) const [virtual]

returns true if the entire buffer has been stored.

Implements buffer_base.

Definition at line 159 of file buffer.cpp.

References span_manager::vector(), and bit_vector::whole().

Referenced by dump(), full_length(), text_form(), and linked_buffer::whole().

bool buffer::empty ( ) const [virtual]

returns true if the buffer has no packets stored yet.

Implements buffer_base.

Definition at line 162 of file buffer.cpp.

References bit_vector::empty(), and span_manager::vector().

Referenced by linked_buffer::empty().

int buffer::full_length ( int offset = 0 ) const [virtual]

returns the full length of this buffer, ignoring first "offset" bytes.

note that this is not known for sure until all packets are present in the buffer. BAD_INPUT is returned if the offset is invalid. INCOMPLETE is returned if the buffer was not whole yet. to receive an estimate of the size before the buffer is complete, use the guess_size() method.

Implements buffer_base.

Definition at line 271 of file buffer.cpp.

References buffer_base::BAD_INPUT, FUNCDEF, buffer_base::INCOMPLETE, and whole().

Referenced by dump(), linked_buffer::full_length(), and text_form().

virtual int buffer::guess_size ( int offset = 0 ) [virtual]

provides an estimate of what the full size will eventually be.

once this figure is seen, it is important that it remain constant; otherwise calculations based on it would be incorrect later. so, the did_estimate() method reports whether the size was ever guessed for this buffer and this function will return the same value until the buffer's released.

Implements buffer_base.

Referenced by linked_buffer::guess_size().

bool buffer::did_estimate ( ) const [virtual]

returns true if we have previously estimated a size for this buffer.

Implements buffer_base.

Definition at line 112 of file buffer.cpp.

Referenced by linked_buffer::did_estimate().

void buffer::reset_estimate ( ) [virtual]

tosses our earlier estimate of the buffer's size.

Implements buffer_base.

Definition at line 110 of file buffer.cpp.

Referenced by linked_buffer::reset_estimate().

int buffer::estimate ( ) const [virtual]

returns our estimate, if we've made one.

Implements buffer_base.

Definition at line 114 of file buffer.cpp.

Referenced by linked_buffer::estimate().

outcome buffer::dump	(	byte_array &	storage_location,
		int	offset = `0`
	)			`[virtual]`

stuffs the entire buffer into contiguous memory at "storage_location".

if the buffer cannot be allocated, OUT_OF_MEMORY is returned. if the buffer is not complete, INCOMPLETE will be returned. if the "offset" is positive, then the packets stored in the buffer will have the first "offset" bytes chopped off of them before they are stored. if any packet is too short for the given offset (or if offset is negative), BAD_INPUT is returned.

Implements buffer_base.

Definition at line 298 of file buffer.cpp.

References buffer_base::BAD_INPUT, full_length(), FUNCDEF, buffer_base::INCOMPLETE, array< contents >::length(), array< contents >::observe(), buffer_base::OKAY, buffer_base::OUT_OF_MEMORY, array< contents >::overwrite(), array< contents >::reset(), time_stamp::reset(), and whole().

Referenced by linked_buffer::dump().

void buffer::release	(	int	packet_number,
		release_style	status_handling = `KEEP_STATUS`
	)			`[virtual]`

frees the storage for the "packet_number"th packet.

if keep_status is true, then packet's state of being present is retained; otherwise, the packet is considered not to have been received yet. if the status is kept, then the packet will appear to be there but will have zero length and a NIL content.

Implements buffer_base.

Definition at line 223 of file buffer.cpp.

References bounds_return, bit_vector::clear(), FUNCDEF, time_stamp::reset(), buffer_base::RESET_STATUS, and span_manager::vector().

Referenced by linked_buffer::release().

void buffer::release ( ) [virtual]

frees the entire buffer, returning it to an unallocated state.

Implements buffer_base.

Definition at line 174 of file buffer.cpp.

References buffer_key::connection, FUNCDEF, buffer_key::msg_id, span_manager::reset(), time_stamp::reset(), and WHACK().

Referenced by ~buffer().

istring buffer::text_form ( ) const [virtual]

returns a text string representing the state of the buffer.