Space Optimized Circular Buffer

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.

Synopsis

namespace boost {

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

   explicit circular_buffer_space_optimized(const allocator_type& alloc = allocator_type());
   explicit circular_buffer_space_optimized(capacity_control capacity_ctrl, const allocator_type& alloc = allocator_type());
   circular_buffer_space_optimized(capacity_control capacity_ctrl, 
      value_type item, const allocator_type& alloc = allocator_type());
   circular_buffer_space_optimized(capacity_control capacity_ctrl, 
      size_type n, value_type item, 
      const allocator_type& alloc = allocator_type());
   template <class InputIterator>
      circular_buffer_space_optimized(InputIterator first, InputIterator last);
   template <class InputIterator>
      circular_buffer_space_optimized(capacity_control capacity_ctrl, InputIterator first, InputIterator last);
   template <class InputIterator>
      circular_buffer_space_optimized(InputIterator first, 
         InputIterator last, const allocator_type& alloc = allocator_type());
   template <class InputIterator>
      circular_buffer_space_optimized(capacity_control capacity_ctrl, 
         InputIterator first, InputIterator last, 
         const allocator_type& alloc = allocator_type());

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

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.

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

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.

Constructors

explicit
            circular_buffer_space_optimized(const allocator_type&
            alloc = allocator_type());

Create an empty space optimized circular buffer with a maximum capacity.

TODO - doc

explicit
            circular_buffer_space_optimized(capacity_control
            capacity_ctrl, 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.

circular_buffer_space_optimized(capacity_control
            capacity_ctrl,

                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.

circular_buffer_space_optimized(capacity_control
            capacity_ctrl,

                size_type n,
            value_type
            item,

                const allocator_type&
            alloc = allocator_type());

TODO doc.

template
            <class InputIterator>

                circular_buffer_space_optimized(InputIterator first, InputIterator last);

template
            <class InputIterator>

                circular_buffer_space_optimized(capacity_control
            capacity_ctrl, InputIterator first, InputIterator last);

template
            <class InputIterator>

                circular_buffer_space_optimized(InputIterator first,

                   InputIterator last, const allocator_type&
            alloc = allocator_type());

TODO doc.

template
            <class InputIterator>

                circular_buffer_space_optimized(capacity_control
            capacity_ctrl,

                   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 - TODO change 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.

Public Member Functions

size_type
            min_capacity() const;

Return the minimal guaranteed amount of allocated memory.

The allocated memory will never drop under this value.

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
            set_capacity(size_type
            new_capacity);

! See the circular_buffer source documentation.

Precondition:

min_capacity() <= new_capacity

Note:

It is considered as a bug if the precondition is not met (i.e. if new_capacity > min_capacity()) and an assertion will be invoked in the debug mode.

void
            resize(size_type
            new_size, value_type
            item = value_type());

See the circular_buffer source documentation.

void
            rset_capacity(size_type
            new_capacity);

! See the circular_buffer source documentation.

Precondition:

min_capacity() <= new_capacity

Note:

It is considered as a bug if the precondition is not met (i.e. if new_capacity > min_capacity()) and an assertion will be invoked in the debug mode.

void
            rresize(size_type
            new_size, value_type
            item = value_type());

See the circular_buffer source documentation.

void
            assign(size_type n,
            value_type
            item);

See the circular_buffer source documentation.

void
            assign(capacity_control
            capacity_ctrl, size_type n,
            value_type
            item);

See the circular_buffer source documentation.

template
            <class InputIterator>

                void assign(capacity_control
            capacity_ctrl, InputIterator first, InputIterator last);

See the circular_buffer source documentation.

void
            swap(circular_buffer_space_optimized<T,Alloc>& cb);

See the circular_buffer source documentation.

void
            push_back(value_type
            item = value_type());

! 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 = value_type());

! See the circular_buffer source documentation.

The rules for iterator invalidation differ from the original circular_buffer. See the documentation.

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.

iterator
            insert(iterator pos,
            value_type
            item = value_type());

! 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.

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.

iterator
            rinsert(iterator pos,
            value_type
            item = value_type());

! 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.

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.

iterator
            erase(iterator
            pos);

! See the circular_buffer source documentation.

The rules for iterator invalidation differ from the original circular_buffer. See the documentation.

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
            rerase(iterator
            pos);

! See the circular_buffer source documentation.

The rules for iterator invalidation differ from the original circular_buffer. See the documentation.

iterator
            rerase(iterator first,
            iterator
            last);

! See the circular_buffer source documentation.

The rules for iterator invalidation differ from the original circular_buffer. See the documentation.

Semantics

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:

Space Optimized Circular Buffer

circular_buffer_space_optimized<T, Alloc>

Contents

Description

Synopsis

Rationale

Header Files

Modeled concepts

Template Parameters, Members and Friend Functions

Constructors

Public Member Functions

Semantics

See also

Acknowledgments


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.