Libosmium  2.2.0
Fast and flexible C++ library for working with OpenStreetMap data
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros
Public Types | Public Member Functions | Private Attributes | Friends | List of all members
osmium::memory::Buffer Class Reference

#include <buffer.hpp>

Public Types

enum  auto_grow : bool { auto_grow::yes = true, auto_grow::no = false }
 
typedef Item value_type
 
template<class T >
using t_iterator = osmium::memory::ItemIterator< T >
 
template<class T >
using t_const_iterator = osmium::memory::ItemIterator< const T >
 
typedef t_iterator
< osmium::OSMEntity
iterator
 
typedef t_const_iterator
< osmium::OSMEntity
const_iterator
 

Public Member Functions

 Buffer () noexcept
 
 Buffer (unsigned char *data, size_t size)
 
 Buffer (unsigned char *data, size_t capacity, size_t committed)
 
 Buffer (size_t capacity, auto_grow auto_grow=auto_grow::yes)
 
 Buffer (const Buffer &)=delete
 
Bufferoperator= (const Buffer &)=delete
 
 Buffer (Buffer &&)=default
 
Bufferoperator= (Buffer &&)=default
 
 ~Buffer ()=default
 
unsigned char * data () const noexcept
 
size_t capacity () const noexcept
 
size_t committed () const noexcept
 
size_t written () const noexcept
 
bool is_aligned () const noexcept
 
void set_full_callback (std::function< void(Buffer &)> full)
 
void grow (size_t size)
 
size_t commit ()
 
void rollback ()
 
size_t clear ()
 
template<class T >
T & get (const size_t offset) const
 
unsigned char * reserve_space (const size_t size)
 
template<class T >
T & add_item (const T &item)
 
void add_buffer (const Buffer &buffer)
 
void push_back (const osmium::memory::Item &item)
 
template<class T >
t_iterator< T > begin ()
 
iterator begin ()
 
template<class T >
t_iterator< T > get_iterator (size_t offset)
 
iterator get_iterator (size_t offset)
 
template<class T >
t_iterator< T > end ()
 
iterator end ()
 
template<class T >
t_const_iterator< T > cbegin () const
 
const_iterator cbegin () const
 
template<class T >
t_const_iterator< T > get_iterator (size_t offset) const
 
const_iterator get_iterator (size_t offset) const
 
template<class T >
t_const_iterator< T > cend () const
 
const_iterator cend () const
 
template<class T >
t_const_iterator< T > begin () const
 
const_iterator begin () const
 
template<class T >
t_const_iterator< T > end () const
 
const_iterator end () const
 
 operator bool () const
 
template<class TCallbackClass >
void purge_removed (TCallbackClass *callback)
 

Private Attributes

std::vector< unsigned char > m_memory
 
unsigned char * m_data
 
size_t m_capacity
 
size_t m_written
 
size_t m_committed
 
auto_grow m_auto_grow {auto_grow::no}
 
std::function< void(Buffer &)> m_full
 

Friends

void swap (Buffer &lhs, Buffer &rhs)
 

Detailed Description

A memory area for storing OSM objects and other items. Each item stored has a type and a length. See the Item class for details.

Data can be added to a buffer piece by piece using reserve_space() and add_item(). After all data that together forms an item is added, it must be committed using the commit() call. Usually this is done through the Builder class and its derived classes.

You can iterate over all items in a buffer using the iterators returned by begin(), end(), cbegin(), and cend().

Buffers exist in two flavours, those with external memory management and those with internal memory management. If you already have some memory with data in it (for instance read from disk), you create a Buffer with external memory managment. It is your job then to free the memory once the buffer isn't used any more. If you don't have memory already, you can create a Buffer object and have it manage the memory internally. It will dynamically allocate memory and free it again after use.

By default, if a buffer gets full it will throw a buffer_is_full exception. You can use the set_full_callback() method to set a callback functor which will be called instead of throwing an exception.

Member Typedef Documentation

These iterators can be used to iterate over all items in a buffer.

Member Enumeration Documentation

Enumerator
yes 
no 

Constructor & Destructor Documentation

osmium::memory::Buffer::Buffer ( )
inlinenoexcept

The constructor without any parameters creates a non-initialized buffer, ie an empty hull of a buffer that has no actual memory associated with it. It can be used to signify end-of-input.

osmium::memory::Buffer::Buffer ( unsigned char *  data,
size_t  size 
)
inlineexplicit

Constructs an externally memory-managed buffer using the given memory and size.

Parameters
dataA pointer to some already initialized data.
sizeThe size of the initialized data.
Exceptions
std::invalid_argumentWhen the size isn't a multiple of the alignment.
osmium::memory::Buffer::Buffer ( unsigned char *  data,
size_t  capacity,
size_t  committed 
)
inlineexplicit

Constructs an externally memory-managed buffer with the given capacity that already contains 'committed' bytes of data.

Parameters
dataA pointer to some (possibly initialized) data.
capacityThe size of the memory for this buffer.
committedThe size of the initialized data. If this is 0, the buffer startes out empty.
Exceptions
std::invalid_argumentWhen the capacity or committed isn't a multiple of the alignment.
osmium::memory::Buffer::Buffer ( size_t  capacity,
auto_grow  auto_grow = auto_grow::yes 
)
inlineexplicit

Create an internally memory-managed buffer with the given capacity. different in that it internally gets dynamic memory of the required size. The dynamic memory will be automatically freed when the Buffer is destroyed.

osmium::memory::Buffer::Buffer ( const Buffer )
delete
osmium::memory::Buffer::Buffer ( Buffer &&  )
default
osmium::memory::Buffer::~Buffer ( )
default

Member Function Documentation

void osmium::memory::Buffer::add_buffer ( const Buffer buffer)
inline

Add committed contents of the given buffer to this buffer.

Note that you have to eventually call commit() to actually commit this data.

template<class T >
T& osmium::memory::Buffer::add_item ( const T &  item)
inline

Add an item to the buffer. The size of the item is stored inside the item, so we know how much memory to copy.

Note that you have to eventually call commit() to actually commit this data.

Template Parameters
TClass of the item to be copied.
Parameters
itemReference to the item to be copied.
Returns
Reference to newly copied data in the buffer.
template<class T >
t_iterator<T> osmium::memory::Buffer::begin ( )
inline
iterator osmium::memory::Buffer::begin ( )
inline
template<class T >
t_const_iterator<T> osmium::memory::Buffer::begin ( ) const
inline
const_iterator osmium::memory::Buffer::begin ( ) const
inline
size_t osmium::memory::Buffer::capacity ( ) const
inlinenoexcept

Returns the capacity of the buffer, ie how many bytes it can contain.

template<class T >
t_const_iterator<T> osmium::memory::Buffer::cbegin ( ) const
inline
const_iterator osmium::memory::Buffer::cbegin ( ) const
inline
template<class T >
t_const_iterator<T> osmium::memory::Buffer::cend ( ) const
inline
const_iterator osmium::memory::Buffer::cend ( ) const
inline
size_t osmium::memory::Buffer::clear ( )
inline

Clear the buffer.

Returns
Number of bytes in the buffer before it was cleared.
size_t osmium::memory::Buffer::commit ( )
inline

Mark currently written bytes in the buffer as committed.

Returns
Last number of committed bytes before this commit.
size_t osmium::memory::Buffer::committed ( ) const
inlinenoexcept

Returns the number of bytes already filled in this buffer.

unsigned char* osmium::memory::Buffer::data ( ) const
inlinenoexcept

Return a pointer to data inside the buffer.

template<class T >
t_iterator<T> osmium::memory::Buffer::end ( )
inline
iterator osmium::memory::Buffer::end ( )
inline
template<class T >
t_const_iterator<T> osmium::memory::Buffer::end ( ) const
inline
const_iterator osmium::memory::Buffer::end ( ) const
inline
template<class T >
T& osmium::memory::Buffer::get ( const size_t  offset) const
inline

Get the data in the buffer at the given offset.

Template Parameters
TType we want to the data to be interpreted as.
Returns
Reference of given type pointing to the data in the buffer.
template<class T >
t_iterator<T> osmium::memory::Buffer::get_iterator ( size_t  offset)
inline
iterator osmium::memory::Buffer::get_iterator ( size_t  offset)
inline
template<class T >
t_const_iterator<T> osmium::memory::Buffer::get_iterator ( size_t  offset) const
inline
const_iterator osmium::memory::Buffer::get_iterator ( size_t  offset) const
inline
void osmium::memory::Buffer::grow ( size_t  size)
inline

Grow capacity of this buffer to the given size. This works only with internally memory-managed buffers. If the given size is not larger than the current capacity, nothing is done. Already written but not committed data is discarded.

Parameters
sizeNew capacity.
bool osmium::memory::Buffer::is_aligned ( ) const
inlinenoexcept

This tests if the current state of the buffer is aligned properly. Can be used for asserts.

osmium::memory::Buffer::operator bool ( ) const
inlineexplicit

In a bool context any initialized buffer is true.

Buffer& osmium::memory::Buffer::operator= ( const Buffer )
delete
Buffer& osmium::memory::Buffer::operator= ( Buffer &&  )
default
template<class TCallbackClass >
void osmium::memory::Buffer::purge_removed ( TCallbackClass *  callback)
inline

Purge removed items from the buffer. This is done by moving all non-removed items forward in the buffer overwriting removed items and then correcting the m_written and m_committed numbers.

Note that calling this function invalidates all iterators on this buffer and all offsets in this buffer.

For every non-removed item that moves its position, the function 'moving_in_buffer' is called on the given callback object with the old and new offsets in the buffer where the object used to be and is now, respectively. This call can be used to update any indexes.

void osmium::memory::Buffer::push_back ( const osmium::memory::Item item)
inline

Add an item to the buffer. This function is provided so that you can use std::back_inserter.

unsigned char* osmium::memory::Buffer::reserve_space ( const size_t  size)
inline

Reserve space of given size in buffer and return pointer to it. This is the only way of adding data to the buffer. You reserve the space and then fill it.

Note that you have to eventually call commit() to actually commit this data.

If there isn't enough space in the buffer, one of three things can happen:

  • If you have set a callback with set_full_callback(), it is called. After the call returns, you must have either grown the buffer or cleared it by calling buffer.clear().
  • If no callback is defined and this buffer uses internal memory management, the buffers capacity is grown, so that the new data will fit.
  • Else the buffer_is_full exception is thrown.
Parameters
sizeNumber of bytes to reserve.
Returns
Pointer to reserved space. Note that this pointer is only guaranteed to be valid until the next call to reserve_space().
Exceptions
osmium::buffer_is_fullMight be thrown if the buffer is full.
void osmium::memory::Buffer::rollback ( )
inline

Roll back changes in buffer to last committed state.

void osmium::memory::Buffer::set_full_callback ( std::function< void(Buffer &)>  full)
inline

Set functor to be called whenever the buffer is full instead of throwing buffer_is_full.

size_t osmium::memory::Buffer::written ( ) const
inlinenoexcept

Returns the number of bytes currently filled in this buffer that are not yet committed.

Friends And Related Function Documentation

void swap ( Buffer lhs,
Buffer rhs 
)
friend

Member Data Documentation

auto_grow osmium::memory::Buffer::m_auto_grow {auto_grow::no}
private
size_t osmium::memory::Buffer::m_capacity
private
size_t osmium::memory::Buffer::m_committed
private
unsigned char* osmium::memory::Buffer::m_data
private
std::function<void(Buffer&)> osmium::memory::Buffer::m_full
private
std::vector<unsigned char> osmium::memory::Buffer::m_memory
private
size_t osmium::memory::Buffer::m_written
private

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