avro::OutputBuffer Class Reference

The OutputBuffer (write-only buffer). More...

#include <Buffer.hh>

List of all members.

Public Types

typedef detail::size_type size_type
typedef detail::data_type data_type
typedef
detail::OutputBufferIterator 
const_iterator
 The asio library expects a const_iterator (the const-ness refers to the fact that the underlying avro of buffers will not be modified, even though the data in those buffers is being modified).

Public Member Functions

 OutputBuffer (size_type reserveSize=0)
 Default constructor.
void reserve (size_type reserveSize)
 Reserve enough space for a wroteTo() operation.
size_type writeTo (const data_type *data, size_type size)
 Write a block of data to the buffer.
template<typename T >
void writeTo (T val)
 Write a single value to the buffer.
size_type wroteTo (size_type size)
 Update the state of the buffer after writing through the iterator interface.
bool empty () const
 Does the buffer have any data?
size_type size () const
 Returns the size of the buffer, in bytes.
size_type freeSpace () const
 Returns the current free space that is available to write to in the buffer, in bytes.
template<class BufferType >
void append (const BufferType &buf)
 Appends the data in the argument to the end of this buffer.
const_iterator begin () const
 Return an iterator pointing to the first data chunk of this buffer that may be written to.
const_iterator end () const
 Return the end iterator for writing.
void discardData ()
 Discard any data in this buffer.
void discardData (size_t bytes)
 Discard the specified number of bytes from this data, starting at the beginning.
InputBuffer extractData (size_type bytes)
 Remove bytes from this buffer, starting from the beginning, and place them into a new buffer.
InputBuffer extractData ()
 Remove all bytes from this buffer, returning them in a new buffer.
OutputBuffer clone () const
 Clone this buffer, creating a copy that contains the same data.
void appendForeignData (const data_type *data, size_type size, const detail::free_func &func)
 Add unmanaged data to the buffer.
int numChunks () const
 Returns the number of chunks that contain free space.
int numDataChunks () const
 Returns the number of chunks that contain data.

Friends

class InputBuffer
class BufferReader

Detailed Description

The OutputBuffer (write-only buffer).

Use cases for OutputBuffer

  1. ASIO access:
    • write to a buffer(s) by asio using iterator
    • convert to read buffer for deserializing

OutputBuffer is assignable and copy-constructable. On copy or assignment, only a pointer is copied, so the two resulting copies are identical, so modifying one will modify both.


Member Typedef Documentation

The asio library expects a const_iterator (the const-ness refers to the fact that the underlying avro of buffers will not be modified, even though the data in those buffers is being modified).

The iterator provides the list of addresses an operation can write to.


Constructor & Destructor Documentation

avro::OutputBuffer::OutputBuffer ( size_type  reserveSize = 0  )  [inline]

Default constructor.

Will pre-allocate at least the requested size, but can grow larger on demand.

Destructor uses the default, which resets a shared pointer, deleting the underlying data if no other copies of exist.

Copy and assignment operators are not explicitly provided because the default ones work fine. The default makes only a shallow copy, so the copies will refer to the same memory. This is required by asio functions, which will implicitly make copies for asynchronous operations. Therefore, the user must be careful that if they create multiple copies of the same OutputBuffer, only one is being modified otherwise undefined behavior may occur.

References reserve().

Referenced by clone().


Member Function Documentation

template<class BufferType >
void avro::OutputBuffer::append ( const BufferType &  buf  )  [inline]

Appends the data in the argument to the end of this buffer.

The argument can be either an InputBuffer or OutputBuffer.

void avro::OutputBuffer::appendForeignData ( const data_type *  data,
size_type  size,
const detail::free_func &  func 
) [inline]

Add unmanaged data to the buffer.

The buffer will not automatically free the data, but it will call the supplied function when the data is no longer referenced by the buffer (or copies of the buffer).

void avro::OutputBuffer::discardData ( size_t  bytes  )  [inline]

Discard the specified number of bytes from this data, starting at the beginning.

Throws if the size is greater than the number of bytes.

References size().

InputBuffer avro::OutputBuffer::extractData (  )  [inline]

Remove all bytes from this buffer, returning them in a new buffer.

After removing data, some freeSpace may remain in this buffer.

InputBuffer avro::OutputBuffer::extractData ( size_type  bytes  )  [inline]

Remove bytes from this buffer, starting from the beginning, and place them into a new buffer.

Throws if the number of requested bytes exceeds the size of the buffer. Data and freeSpace in the buffer after bytes remains in this buffer.

References size().

size_type avro::OutputBuffer::freeSpace (  )  const [inline]

Returns the current free space that is available to write to in the buffer, in bytes.

This is not a strict limit in size, as writeTo() can automatically increase capacity if necessary.

Referenced by wroteTo().

void avro::OutputBuffer::reserve ( size_type  reserveSize  )  [inline]

Reserve enough space for a wroteTo() operation.

When using writeTo(), the buffer will grow dynamically as needed. But when using the iterator to write (followed by wroteTo()), data may only be written to the space available, so this ensures there is enough room in the buffer before the write operation.

Referenced by OutputBuffer().

template<typename T >
void avro::OutputBuffer::writeTo ( val  )  [inline]

Write a single value to the buffer.

The buffer size will automatically grow if there is not room for the byte. The value must be a "fundamental" type, e.g. int, float, etc. (otherwise use the other writeTo tests).

size_type avro::OutputBuffer::writeTo ( const data_type *  data,
size_type  size 
) [inline]

Write a block of data to the buffer.

The buffer size will automatically grow if the size is larger than what is currently free.

Referenced by avro::ostreambuf::overflow(), and avro::ostreambuf::xsputn().

size_type avro::OutputBuffer::wroteTo ( size_type  size  )  [inline]

Update the state of the buffer after writing through the iterator interface.

This function exists primarily for the boost:asio which writes directly to the buffer using its iterator. In this case, the internal state of the buffer does not reflect that the data was written This informs the buffer how much data was written.

The buffer does not automatically resize in this case, the bytes written cannot exceed the amount of free space. Attempting to write more will throw a std::length_error exception.

References freeSpace().


The documentation for this class was generated from the following file:
Generated on Thu Sep 2 18:40:54 2010 for Avro C++ by  doxygen 1.6.3