atoms::Buffer Class Reference

#include <buffer.hh>

Collaboration diagram for atoms::Buffer:

[legend]List of all members.

Detailed Description

I/O buffer.

This class is primarily intended for use in the BufferedStreamFilter class. It is an independent, publically-accessible class to aid unit testing and because in the future, high-performance applications may directly access buffers.

It is similar to Java's java.nio.Buffer class, and I've deliberately chosen the variable names to be the same as theirs.

The main buffer region starts at position and extends until limit (and thus is of size limit - position.) There are two main reasons it is not simple a buffer region starting at 0:

Efficiency of data retrieval. Keeping a starting index means that it's not necessary to memove() the entire contents of the buffer after retrieving data. This would be an O(n) operation with the size of the buffer. This way, it is O(n) with the size of the retrieval, which is much better.
Rolling back after an IOBlockError. See BufferedStream::AtomicReadMon for details, but this requires keeping a region we are guaranteed to be able to roll back to.

There is also a third benefit as a side effect:

Efficiency of some seeks. This method keeps around data from the recent past, though it discards it when this would cause an extra reallocation. Thus, this avoids a seek and read on the underlying stream in some cases. In practice, I'm not sure how valuable this is, but it comes at no extra cost.

Thread safety:: No; callers are expected to provide their own locks around any access as necessary.

Definition at line 53 of file buffer.hh.

Public Member Functions

Buffer ()

~Buffer ()

Destroys the buffer.

void append (const void *src, size_t n)

Appends n bytes to the buffer.

template<typename internT, typename externT, typename stateT> void append (const internT *from, const internT *fromEnd, stateT &, const std::codecvt< internT, externT, stateT > &)

void replace (const void *src, size_t p, size_t n)

Replaces up to n bytes beginning at p, extending the buffer if necessary.

void shift (void *dest, size_t n)

Copies n bytes from the beginning of the buffer and removes them.

size_t truncate (size_t n)

Truncates the buffer to length n.

size_t getSize () const

Returns the current size of the main region.

size_t getCapacity () const

Returns the current capacity of the buffer.

size_t getRollbackSize () const

Returns the current size of the rollback region.

void setMark ()

Sets a mark at the current position.

void rollback ()

Rolls back to the mark.

void rollback (size_t n)

Rolls back n bytes.

void clear ()

Clears the mark.

size_t readAndAppend (Stream *s, size_t min)

size_t readAndAppend (const boost::shared_ptr< Stream > &s, size_t min)

size_t writeAndShift (Stream *s, size_t max)

size_t writeAndShift (const boost::shared_ptr< Stream > &s, size_t max)

Private Member Functions

void prepareForAppend (size_t n)

Ensures there is capacity to append n bytes.

Private Attributes

size_t position

The start of meaningful data within the buffer.

size_t limit

First free byte within the buffer.

size_t capacity

The first byte beyond the allocation of the buffer.

char * buf

The buffer itself, allocated and deallocated with C-style functions.

size_t mark

bool markSet

Static Private Attributes

size_t MINIMUM_ALLOCATION = 1024

This is smallest chunk of memory we'll ever allocate.

DebugLogger LOGGER

Constructor & Destructor Documentation

atoms::Buffer::Buffer ( ) [inline]

Definition at line 55 of file buffer.hh.

atoms::Buffer::~Buffer ( ) [inline]

Destroys the buffer.

Precondition:
No mark is set.

Definition at line 61 of file buffer.hh.

Member Function Documentation

template<typename internT, typename externT, typename stateT>

void atoms::Buffer::append ( const internT * from,

const internT * fromEnd,

stateT & ,

const std::codecvt< internT, externT, stateT > &

)

Definition at line 237 of file buffer.hh.

void atoms::Buffer::append ( const void * src,

size_t n

)

Appends n bytes to the buffer.
In preparation, it may cause the non-guaranteed rollback region to be destroyed. Adjusts the size of the buffer to reflect the read.
Exceptions:

MemoryError if reallocation is necessary and impossible. The buffer will be unmodified.

Definition at line 35 of file buffer.cc.
References buf, limit, NULL, and prepareForAppend().

Here is the call graph for this function:

void atoms::Buffer::clear ( void ) [inline]

Clears the mark.

Precondition:
A mark is set.

See also:
mark, clear, BufferedStream::AtomicReadMon

Definition at line 190 of file buffer.hh.
References markSet.

size_t atoms::Buffer::getCapacity ( void ) const [inline]

Returns the current capacity of the buffer.

Definition at line 146 of file buffer.hh.
References position.

size_t atoms::Buffer::getRollbackSize ( ) const [inline]

Returns the current size of the rollback region.

Definition at line 149 of file buffer.hh.

size_t atoms::Buffer::getSize ( void ) const [inline]

Returns the current size of the main region.

Definition at line 143 of file buffer.hh.
References capacity.

void atoms::Buffer::prepareForAppend ( size_t n ) [private]

Ensures there is capacity to append n bytes.
If necessary, the non-guaranteed rollback region will be destroyed.
Definition at line 76 of file buffer.cc.
References buf, capacity, limit, atoms::DebugLogger::log(), LOGGER, mark, markSet, std::max(), MINIMUM_ALLOCATION, NULL, and position.
Referenced by append(), readAndAppend(), and replace().

Here is the call graph for this function:

size_t atoms::Buffer::readAndAppend ( const boost::shared_ptr< Stream > & s,

size_t min

) [inline]

In preparation, it may cause the non-guaranteed rollback region to be destroyed. Adjusts the size of the buffer to reflect the read.
Parameters:

s The stream to read from

min The minimum number of bytes to attempt to read. (This is not the minimum number of bytes that will actually be read into the buffer. That's 1.)

Exceptions:

MemoryError if reallocation is necessary and impossible. The buffer will be unmodified.

IOError when thrown by the Stream

Returns:
The number of bytes read, 1 or higher; may have little relation to min.

Definition at line 82 of file buffer.hh.

size_t atoms::Buffer::readAndAppend ( Stream * s,

size_t min

)

In preparation, it may cause the non-guaranteed rollback region to be destroyed. Adjusts the size of the buffer to reflect the read.
Parameters:

s The stream to read from

min The minimum number of bytes to attempt to read. (This is not the minimum number of bytes that will actually be read into the buffer. That's 1.)

Exceptions:

MemoryError if reallocation is necessary and impossible. The buffer will be unmodified.

IOError when thrown by the Stream

Returns:
The number of bytes read, 1 or higher; may have little relation to min.

Definition at line 26 of file buffer.cc.
References buf, capacity, limit, std::min(), NULL, prepareForAppend(), and atoms::Stream::read().

Here is the call graph for this function:

void atoms::Buffer::replace ( const void * src,

size_t p,

size_t n

)

Replaces up to n bytes beginning at p, extending the buffer if necessary.
In preparation, it may cause the non-guaranteed rollback region to be destroyed. Adjusts the size of the buffer to reflect the read.
Exceptions:

MemoryError if reallocation is necessary and impossible. The buffer will be unmodified.

Definition at line 42 of file buffer.cc.
References buf, limit, NULL, position, and prepareForAppend().

Here is the call graph for this function:

void atoms::Buffer::rollback ( size_t n ) [inline]

Rolls back n bytes.

Definition at line 177 of file buffer.hh.
References mark, markSet, and position.

void atoms::Buffer::rollback ( ) [inline]

Rolls back to the mark.

Precondition:
A mark is set.

See also:
mark, clear, BufferedStream::AtomicReadMon

Definition at line 168 of file buffer.hh.
References mark, markSet, and position.

void atoms::Buffer::setMark ( ) [inline]

Sets a mark at the current position.
The buffer can be rolled back to this state with a reset.
Precondition:
No mark is set.

See also:
mark, clear, BufferedStream::AtomicReadMon

Definition at line 157 of file buffer.hh.
References mark, markSet, and position.

void atoms::Buffer::shift ( void * dest,

size_t n

)

Copies n bytes from the beginning of the buffer and removes them.
The bytes remain in the rollback region, but the position pointer is advanced.
Parameters:

dest The destination, or NULL if the bytes are to be discarded.

n The number of bytes.

Precondition:
The buffer contains at least n bytes.

Definition at line 62 of file buffer.cc.
References buf, limit, NULL, and position.

size_t atoms::Buffer::truncate ( size_t n )

Truncates the buffer to length n.

Returns:
The number of bytes that were truncated.

Definition at line 69 of file buffer.cc.
References limit, and position.

size_t atoms::Buffer::writeAndShift ( const boost::shared_ptr< Stream > & s,

size_t max

) [inline]

The bytes remain in the rollback region, but the position pointer is advanced.
Precondition:
The buffer contains at least max bytes.

Exceptions:

IOError when thrown by the Stream

Returns:
The number of bytes written

Definition at line 121 of file buffer.hh.

size_t atoms::Buffer::writeAndShift ( Stream * s,

size_t max

)

The bytes remain in the rollback region, but the position pointer is advanced.
Precondition:
The buffer contains at least max bytes.

Exceptions:

IOError when thrown by the Stream

Returns:
The number of bytes written

Definition at line 54 of file buffer.cc.
References buf, limit, std::max(), NULL, position, and atoms::Stream::write().

Here is the call graph for this function:

Member Data Documentation

char* atoms::Buffer::buf [private]

The buffer itself, allocated and deallocated with C-style functions.
Always NULL when not memory is allocated.
Definition at line 228 of file buffer.hh.
Referenced by append(), prepareForAppend(), readAndAppend(), replace(), shift(), and writeAndShift().

size_t atoms::Buffer::capacity [private]

The first byte beyond the allocation of the buffer.

Definition at line 222 of file buffer.hh.
Referenced by getSize(), prepareForAppend(), and readAndAppend().

size_t atoms::Buffer::limit [private]

First free byte within the buffer.

Invariant:
buf <= limit && limit <= capacity

Definition at line 219 of file buffer.hh.
Referenced by append(), prepareForAppend(), readAndAppend(), replace(), shift(), truncate(), and writeAndShift().

DebugLogger atoms::Buffer::LOGGER [static, private]

Referenced by prepareForAppend().

size_t atoms::Buffer::mark [private]

If markSet is false, mark's contents are undefined. Otherwise, the standard invariant applies.
Definition at line 208 of file buffer.hh.
Referenced by prepareForAppend(), rollback(), and setMark().

bool atoms::Buffer::markSet [private]

If markSet is false, mark's contents are undefined. Otherwise, the standard invariant applies.
Definition at line 209 of file buffer.hh.
Referenced by clear(), prepareForAppend(), rollback(), and setMark().

size_t atoms::Buffer::MINIMUM_ALLOCATION = 1024 [static, private]

This is smallest chunk of memory we'll ever allocate.

Definition at line 22 of file buffer.cc.
Referenced by prepareForAppend().

size_t atoms::Buffer::position [private]

The start of meaningful data within the buffer.

Definition at line 213 of file buffer.hh.
Referenced by getCapacity(), prepareForAppend(), replace(), rollback(), setMark(), shift(), truncate(), and writeAndShift().

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

atoms/buffer.hh
atoms/buffer.cc

Generated on Wed Jun 15 01:20:38 2005 for atoms++ by

1.3.5


Public Member Functions
	Buffer ()
	~Buffer ()
	Destroys the buffer.
void	append (const void *src, size_t n)
	Appends n bytes to the buffer.
template<typename internT, typename externT, typename stateT> void	append (const internT from, const internT fromEnd, stateT &, const std::codecvt< internT, externT, stateT > &)
void	replace (const void *src, size_t p, size_t n)
	Replaces up to n bytes beginning at p, extending the buffer if necessary.
void	shift (void *dest, size_t n)
	Copies n bytes from the beginning of the buffer and removes them.
size_t	truncate (size_t n)
	Truncates the buffer to length n.
size_t	getSize () const
	Returns the current size of the main region.
size_t	getCapacity () const
	Returns the current capacity of the buffer.
size_t	getRollbackSize () const
	Returns the current size of the rollback region.
void	setMark ()
	Sets a mark at the current position.
void	rollback ()
	Rolls back to the mark.
void	rollback (size_t n)
	Rolls back n bytes.
void	clear ()
	Clears the mark.

size_t	readAndAppend (Stream *s, size_t min)
size_t	readAndAppend (const boost::shared_ptr< Stream > &s, size_t min)

size_t	writeAndShift (Stream *s, size_t max)
size_t	writeAndShift (const boost::shared_ptr< Stream > &s, size_t max)
Private Member Functions
void	prepareForAppend (size_t n)
	Ensures there is capacity to append n bytes.
Private Attributes
size_t	position
	The start of meaningful data within the buffer.
size_t	limit
	First free byte within the buffer.
size_t	capacity
	The first byte beyond the allocation of the buffer.
char *	buf
	The buffer itself, allocated and deallocated with C-style functions.

size_t	mark
bool	markSet
Static Private Attributes
size_t	MINIMUM_ALLOCATION = 1024
	This is smallest chunk of memory we'll ever allocate.
DebugLogger	LOGGER