Space Optimized Circular Buffer Container Adaptor

circular_buffer_space_optimized<T, Alloc>

 Boost

Contents

Description
Synopsis
Rationale
Header files
Modeled concepts
Template Parameters, Members and Standalone Functions
Semantics
See also
Acknowledgments

Description

The circular_buffer_space_optimized container is an adaptor of the circular_buffer. The functionality of the circular_buffer_space_optimized is similar to the base circular_buffer except it does not allocate memory at once when created rather it allocates memory as needed. (The predictive memory allocation is similar to typical std::vector implementation.) Moreover the memory is automatically freed as the size of the container decreases.

Space Optimized Circular Buffer
Figure: The memory allocation process of the space optimized circular buffer. The min_capacity represents the minimal guaranteed amount of allocated memory. The allocated memory will never drop under this value. By default the min_capacity is set to 0.

Synopsis 

namespace boost {

template <class T, class Alloc>
class circular_buffer_space_optimized
{
public:
   typedef Alloc allocator_type;
   typedef implementation-defined const_iterator;
   typedef typename Alloc::const_pointer const_pointer;
   typedef typename Alloc::const_reference const_reference;
   typedef implementation-defined const_reverse_iterator;
   typedef typename Alloc::difference_type difference_type;
   typedef implementation-defined iterator;
   typedef typename Alloc::pointer pointer;
   typedef typename Alloc::reference reference;
   typedef implementation-defined reverse_iterator;
   typedef typename Alloc::size_type size_type;
   typedef typename Alloc::value_type value_type;

   template <class InputIterator>
      circular_buffer_space_optimized(size_type capacity, 
         size_type min_capacity, InputIterator first, 
         InputIterator last, const allocator_type& alloc = allocator_type());
   circular_buffer_space_optimized(size_type capacity, 
      size_type min_capacity, value_type item, 
      const allocator_type& alloc = allocator_type());
   explicit circular_buffer_space_optimized(size_type capacity, 
      size_type min_capacity = 0, const allocator_type& alloc = allocator_type());

   template <class InputIterator>
      void assign(InputIterator first, InputIterator last);
   void assign(size_type n, value_type item);
   value_type at(size_type index) const;
   reference at(size_type index);
   value_type back() const;
   reference back();
   const_iterator begin() const;
   iterator begin();
   size_type capacity() const;
   void clear();
   pointer data();
   bool empty() const;
   const_iterator end() const;
   iterator end();
   iterator erase(iterator first, iterator last);
   iterator erase(iterator pos);
   value_type front() const;
   reference front();
   bool full() const;
   allocator_type& get_allocator();
   allocator_type get_allocator() const;
   template <class InputIterator>
      void insert(iterator pos, InputIterator first, InputIterator last);
   void insert(iterator pos, size_type n, value_type item);
   iterator insert(iterator pos);
   iterator insert(iterator pos, value_type item);
   size_type max_size() const;
   size_type min_capacity() const;
   circular_buffer_space_optimized<T,Alloc>& operator=(const circular_buffer_space_optimized<T,Alloc>& cb);
   value_type operator[](size_type index) const;
   reference operator[](size_type index);
   void pop_back();
   void pop_front();
   void push_back();
   void push_back(value_type item);
   void push_front();
   void push_front(value_type item);
   const_reverse_iterator rbegin() const;
   reverse_iterator rbegin();
   const_reverse_iterator rend() const;
   reverse_iterator rend();
   void resize(size_type new_size, value_type item = T(), bool remove_front = true);
   template <class InputIterator>
      void rinsert(iterator pos, InputIterator first, InputIterator last);
   void rinsert(iterator pos, size_type n, value_type item);
   iterator rinsert(iterator pos);
   iterator rinsert(iterator pos, value_type item);
   void set_capacity(size_type new_capacity, bool remove_front = true);
   void set_min_capacity(size_type new_min_capacity);
   size_type size() const;
   void swap(circular_buffer_space_optimized& cb);
};

template <class T, class Alloc>
   bool operator!=(const circular_buffer_space_optimized<T,Alloc>& lhs, 
      const circular_buffer_space_optimized<T,Alloc>& rhs);
template <class T, class Alloc>
   bool operator<(const circular_buffer_space_optimized<T,Alloc>& lhs, 
      const circular_buffer_space_optimized<T,Alloc>& rhs);
template <class T, class Alloc>
   bool operator<=(const circular_buffer_space_optimized<T,Alloc>& lhs, 
      const circular_buffer_space_optimized<T,Alloc>& rhs);
template <class T, class Alloc>
   bool operator==(const circular_buffer_space_optimized<T,Alloc>& lhs, 
      const circular_buffer_space_optimized<T,Alloc>& rhs);
template <class T, class Alloc>
   bool operator>(const circular_buffer_space_optimized<T,Alloc>& lhs, 
      const circular_buffer_space_optimized<T,Alloc>& rhs);
template <class T, class Alloc>
   bool operator>=(const circular_buffer_space_optimized<T,Alloc>& lhs, 
      const circular_buffer_space_optimized<T,Alloc>& rhs);
template <class T, class Alloc>
   void swap(circular_buffer_space_optimized<T,Alloc>& lhs, 
      circular_buffer_space_optimized<T,Alloc>& rhs);

} // namespace boost

Rationale

The auto-resizing mode of the space optimized circular buffer can be useful in situations when the container can possibly store large number of elements but most of its lifetime the container stores just few of them. The usage of the circular_buffer_space_optimized will result in decreased memory consumption and can improve the CPU cache effectiveness.

Header files

The circular_buffer_space_optimized is defined in the file boost/circular_buffer.hpp. There is also a forward declaration for the circular_buffer_space_optimized in the header file boost/circular_buffer_fwd.hpp.

Modeled concepts

Random Access Container, Front Insertion Sequence, Back Insertion Sequence, Assignable (SGI specific), Equality Comparable, LessThan Comparable (SGI specific)

Template Parameters, Members and Friend Functions

Template parameters, members and friend functions of the circular_buffer_space_optimized are almost the same as for the base circular_buffer. Refer the circular_buffer documentation and also its source code documentation for a detailed description.

The specific methods of the circular_buffer_space_optimized are listed below.

Constructors

template <class InputIterator>
    circular_buffer_space_optimized(size_type capacity,
       size_type min_capacity, InputIterator first,
       InputIterator last, const allocator_type& alloc = allocator_type());
   
Create a space optimized circular buffer with a copy of a range.
Precondition: capacity >= min_capacity and valid range [first, last).
Postcondition: (*this).capacity() == capacity
Allocates at least as much memory as specified by the min_capacity parameter.
If the number of items to copy from the range [first, last) is greater than the specified capacity then only elements from the range [last - capacity, last) will be copied.
Note: It is considered as a bug if the precondition is not met (i.e. if capacity < min_capacity) and an assertion will be invoked in the debug mode.
circular_buffer_space_optimized(size_type capacity,
    size_type min_capacity, value_type item,
    const allocator_type& alloc = allocator_type());
   
Create a full space optimized circular buffer filled with copies of item.
Precondition: capacity >= min_capacity
Postcondition: (*this).size() == capacity && (*this)[0] == (*this)[1] == ... == (*this).back() == item
Note: It is considered as a bug if the precondition is not met (i.e. if capacity < min_capacity) and an assertion will be invoked in the debug mode.
explicit circular_buffer_space_optimized(size_type capacity,
    size_type min_capacity = 0, const allocator_type& alloc = allocator_type());
   
Create an empty space optimized circular buffer with a given capacity.
Precondition: capacity >= min_capacity
Postcondition: (*this).capacity() == capacity && (*this).size == 0
Allocates memory specified by the min_capacity parameter.
Note: It is considered as a bug if the precondition is not met (i.e. if capacity < min_capacity) and an assertion will be invoked in the debug mode.

Public Member Functions

iterator erase(iterator first, iterator last);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
iterator erase(iterator pos);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
template <class InputIterator>
    void insert(iterator pos, InputIterator first, InputIterator last);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
void insert(iterator pos, size_type n, value_type item);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
iterator insert(iterator pos);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
iterator insert(iterator pos, value_type item);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
size_type min_capacity() const;
   
Return the minimal guaranteed amount of allocated memory.
void pop_back();
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
void pop_front();
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
void push_back();
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
void push_back(value_type item);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
void push_front();
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
void push_front(value_type item);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
template <class InputIterator>
    void rinsert(iterator pos, InputIterator first, InputIterator last);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
void rinsert(iterator pos, size_type n, value_type item);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
iterator rinsert(iterator pos);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
iterator rinsert(iterator pos, value_type item);
   
! See the circular_buffer source documentation.
The rules for iterator invalidation differ from the original circular_buffer. See the documentation.
void set_capacity(size_type new_capacity, bool remove_front = true);
   
! See the circular_buffer source documentation.
Precondition: (*this).min_capacity() <= new_capacity
Note: It is considered as a bug if the precondition is not met (i.e. if new_capacity > (*this).min_capacity()) and an assertion will be invoked in the debug mode.
void set_min_capacity(size_type new_min_capacity);
   
Change the minimal guaranteed amount of allocated memory.
Precondition: (*this).capacity() >= new_min_capacity
Postcondition: (*this).min_capacity() == new_min_capacity Allocates memory specified by the new_min_capacity parameter.
Note: It is considered as a bug if the precondition is not met (i.e. if new_min_capacity > (*this).capacity()) and an assertion will be invoked in the debug mode.
void swap(circular_buffer_space_optimized& cb);
   
See the circular_buffer source documentation.

Semantics

The behaviour of memory auto-resizing is as follows:

The semantics of the circular_buffer_space_optimized then follows the semantics of the base circular_buffer except the invalidation rules.

The rule for iterator invalidation for circular_buffer_space_optimized is as follows:

See also

boost::circular_buffer, std::vector

Acknowledgments

The idea of the space optimized circular buffer has been introduced by Pavel Vozenilek.