Templated Circular Buffer Container

In general the term circular buffer refers to an area in memory which is used to store incoming data. When the buffer is filled, new data is written starting at the beginning of the buffer and overwriting the old. [1] (Also see the Figure.)

The circular_buffer is a STL compliant container. It is a kind of sequence that, like std::vector or std::deque, supports random access iterators. In addition, it supports constant time insert and erase operations at the beginning or the end of the buffer. The circular_buffer is specially designed to provide fixed capacity storage. When its capacity is exhausted, newly inserted elements will cause elements either at the beginning or end of the buffer (depending on what insert operation is used) to be overwritten.

There are also several container adaptors which are bundled with the circular_buffer:
TODO
The circular_buffer only allocates memory when created, when the capacity is adjusted explicitly, or as necessary to accommodate a resizing or assign operation. (There is also a

circular_buffer_space_optimized

available. It is an adaptor of the circular_buffer which does not allocate memory at once when created rather it allocates memory as needed.

Simple Example

Rationale

TODO motivation The most likely usage of the circular_buffer is as a storage of the most recently received samples, overwriting the oldest as new samples arrive.

A contiguous region of memory utilized as a circular buffer has several unique and useful characteristics:

The


                circular_buffer

container provides a similar interface to


                std::vector


                std::deque

and


                std::list

including


                push

pop


                insert


                erase

, iterators and compatibility with

std

algorithms.

The design of the


                circular_buffer

container is guided by the following principles:

Thread-Safety

Like all STL containers, also the circular_buffer is not thread-safe. E.g. if one thread writes to a


                std::vector

and another reads from it, the threads have to be synchronized. The same applies to threads accessing the


                circular_buffer

Writing to a Full Buffer

There are several options how to cope with the case if a data source produces more data than can fit in the buffer [link to wikipedia]:

Reading from an Empty Buffer

Iterator Invalidation

According to the STL container specification [link to container SGI STL] the


                circular_buffer

provides several types of iterator. An iterator is usually considered to be invalidated if an element, the iterator pointed to, had been removed or overwritten by another element. The source documentation refers to this definition of iterator invalidation and this definition is also enforced by the Debug Support [link]. However, some applications utilizing


                circular_buffer

may require less strict definition: an iterator is invalidated only if it points to an uninitialized memory. Consider following example:

TODO This example works only if the Debug Support is disabled otherwise the code will produce a runtime error. [link how to disable debug support]

Overwrite Operation

There was a discussion what exactly "overwriting of an element" means. It can be either a destruction of the original element and a consequent inplace construction of a new element or it can be an assignment of a new element into an old one.

Producer-Consumer Mode

It it misleading to claim that the


                    circular_buffer

can be used as a bounded buffer in a producer-consumer mode. Similarly to the


                    circular_buffer

the bounded buffer has a fixed size, but it was primarily designed to be used in the producer-consumer mode when one thread is writing to the buffer and another is reading from it, which implies the bounded buffer is thread-safe. As discussed in the Thread-Safety section the


                    circular_buffer

is not thread-safe which prevents the


                    circular_buffer

to be used as a bounded buffer or at least to be used directly. It is of course possible to write a wrapper or an adaptor which will then synchronize the read/write access to the


                    circular_buffer

Moreover the


                    circular_buffer

was designed to overwrite old elements with new ones when its capacity is exhauted. Although this behaviour is very useful it represents only one option how a bounded buffer can behave. E.g. when a bounded buffer is full and one thread tries to push an element into it the buffer suspends the thread until some other thread performs a pop operation. Another example is that it can throw an overflow exception when the buffer is full or an underflow exception when it is empty. Considering writing an adaptor which would then serve as a bounded buffer, the


                    circular_buffer

does not have to be always the best choice. The


                    circular_buffer

bears an overhead for its "circular" behavior, so containers like


                    std::vector


                    std::deque

suit better if you do not require the bounded buffer to be circular.

Synopsis

Header Files

Modeled Concepts

Template Parameters

Parameter	Description	Default
`T`	The type of the elements stored in the circular buffer.
`Alloc`	The allocator type used for all internal memory management.	`std::allocator<T>`

Public Types

Type	Description
`allocator_type`	The type of the allocator used in the circular buffer.
`array_range`	An array range.
`const_array_range`	A range of a const array.
`const_iterator`	Const (random access) iterator used to iterate through a circular buffer.
`const_pointer`	Const pointer to the element.
`const_reference`	Const reference to the element.
`const_reverse_iterator`	Const iterator used to iterate backwards through a circular buffer.
`difference_type`	Distance type.
`iterator`	Iterator (random access) used to iterate through a circular buffer.
`pointer`	Pointer to the element.
`reference`	Reference to the element.
`reverse_iterator`	Iterator used to iterate backwards through a circular buffer.
`size_type`	Size type.
`value_type`	The type of the elements stored in the circular buffer.

Constructors and Destructor

Public Member Functions


              const_array_range array_one() const;

TODO doc.


              array_range array_one();

TODO doc.


              const_array_range array_two() const;

TODO doc.


              array_range array_two();

TODO doc.


              
      template <class InputIterator>
   
    void assign(size_type capacity, InputIterator first, InputIterator last);

TODO doc.


              
      template <class InputIterator>
   
    void assign(InputIterator first, InputIterator last);

Assign a copy of range.

Precondition: Valid range [first, last).

Postcondition: (*this).capacity() == std::distance(first, last) && (*this).size() == std::distance(first, last)

Note:

For iterator invalidation see the documentation.


              void assign(size_type capacity, size_type n, value_type item);

TODO doc.


              void assign(size_type n, value_type item);

Assign n items into the circular buffer.

Postcondition: (*this).capacity() == n && (*this).size() == n && (*this)[0] == (*this)[1] == ... == (*this).back() == item

Note:

For iterator invalidation see the documentation.


              value_type at(size_type index) const;

Return the element at the index position.


              reference at(size_type index);

Return the element at the index position.


              value_type back() const;

Return the last (rightmost) element.

Precondition: !*(this).empty()


              reference back();

Return the last (rightmost) element.

Precondition: !*(this).empty()


              const_iterator begin() const;

Return a const iterator pointing to the beginning of the circular buffer.


              iterator begin();

Return an iterator pointing to the beginning of the circular buffer.


              size_type capacity() const;

Return the capacity of the circular buffer.


              void clear();

Erase all stored elements.

Postcondition:

(*this).size() == 0

Note:

For iterator invalidation see the documentation.


              bool empty() const;

Is the circular buffer empty?

Returns: true if there are no elements stored in the circular buffer. false otherwise.


              const_iterator end() const;

Return a const iterator pointing to the end of the circular buffer.


              iterator end();

Return an iterator pointing to the end of the circular buffer.


              iterator erase(iterator first, iterator last);

Erase the range [first, last).

Precondition: Valid range [first, last). size_type old_size = (*this).size()

Postcondition: (*this).size() == old_size - std::distance(first, last)
Removes the elements from the range [first, last).

Returns: iterator to the first element remaining beyond the removed element or (*this).end() if no such element exists.

Note:

For iterator invalidation see the documentation.


              iterator erase(iterator pos);

Erase the element at the given position.

Precondition: Valid pos iterator. size_type old_size = (*this).size()

Postcondition: (*this).size() == old_size - 1
Removes an element at the position pos.

Returns: iterator to the first element remaining beyond the removed element or (*this).end() if no such element exists.

Note:

For iterator invalidation see the documentation.


              value_type front() const;

Return the first (leftmost) element.

Precondition: !*(this).empty()


              reference front();

Return the first (leftmost) element.

Precondition: !*(this).empty()


              bool full() const;

Is the circular buffer full?

Returns: true if the number of elements stored in the circular buffer equals the capacity of the circular buffer. false otherwise.


              allocator_type& get_allocator();

Return the allocator.

Note:

This method was added in order to optimize obtaining of the allocator with a state, although use of stateful allocators in STL is discouraged.


              allocator_type get_allocator() const;

Return the allocator.


              
      template <class InputIterator>
   
    void insert(iterator pos, InputIterator first, InputIterator last);

Insert the range [first, last) before the given position.

Precondition: Valid pos iterator and valid range [first, last).

Postcondition: This operation preserves the capacity of the circular buffer. If the insertion would result in exceeding the capacity of the circular buffer then the necessary number of elements from the beginning (left) of the circular buffer will be removed or not the whole range will be inserted or both. In case the whole range cannot be inserted it will be inserted just some elements from the end (right) of the range (see the example).Example: array to insert: int array[] = { 5, 6, 7, 8, 9 }; original circular buffer |1|2|3|4| | | - capacity: 6, size: 4 position ---------------------^ insert(position, array, array + 5); (If the operation won't preserve capacity, the buffer would look like this |1|2|5|6|7|8|9|3|4|) RESULTING circular buffer |6|7|8|9|3|4| - capacity: 6, size: 6

Note:

For iterator invalidation see the documentation.


              void insert(iterator pos, size_type n, value_type item);

Insert n copies of the item before the given position.

Precondition: Valid pos iterator.

Postcondition: This operation preserves the capacity of the circular buffer. If the insertion would result in exceeding the capacity of the circular buffer then the necessary number of elements from the beginning (left) of the circular buffer will be removed or not all n elements will be inserted or both.Example: original circular buffer |1|2|3|4| | | - capacity: 6, size: 4 position ---------------------^ insert(position, (size_t)5, 6); (If the operation won't preserve capacity, the buffer would look like this |1|2|6|6|6|6|6|3|4|) RESULTING circular buffer |6|6|6|6|3|4| - capacity: 6, size: 6

Note:

For iterator invalidation see the documentation.


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

Insert the item before the given position.

Precondition: Valid pos iterator.

Postcondition: The item will be inserted at the position pos.
If the circular buffer is full, the first (leftmost) element will be removed.

Returns:

iterator to the inserted element.

Note:

For iterator invalidation see the documentation.


              pointer linearize();

TODO doc - Return pointer to data stored in the circular buffer as a continuous array of values.

This method can be useful e.g. when passing the stored data into the legacy C API.

Postcondition: &(*this)[0] < &(*this)[1] < ... < &(*this).back()

Returns:

0 if empty.

Note:

For iterator invalidation see the documentation.


              size_type max_size() const;

Return the largest possible size (or capacity) of the circular buffer.


              circular_buffer<T,Alloc>& operator=(const circular_buffer<T,Alloc>& cb);

Assignment operator.

Postcondition: *this == cb

Note:

For iterator invalidation see the documentation.


              value_type operator[](size_type index) const;

Return the element at the index position.

Precondition: *(this).size() > index


              reference operator[](size_type index);

Return the element at the index position.

Precondition: *(this).size() > index


              void pop_back();

Remove the last (rightmost) element.

Precondition: !*(this).empty() iterator it = ((*this).end() - 1)

Postcondition: ((*this).end() - 1) != it

Note:

For iterator invalidation see the documentation.


              void pop_front();

Remove the first (leftmost) element.

Precondition: !*(this).empty() iterator it = (*this).begin()

Postcondition: (*this).begin() != it

Note:

For iterator invalidation see the documentation.


              void push_back(value_type item = value_type());

Insert a new element at the end.

Postcondition: (*this).back() == item
If the circular buffer is full, the first (leftmost) element will be removed.

Note:

For iterator invalidation see the documentation.


              void push_front(value_type item = value_type());

Insert a new element at the start.

Postcondition: (*this).front() == item
If the circular buffer is full, the last (rightmost) element will be removed.

Note:

For iterator invalidation see the documentation.


              const_reverse_iterator rbegin() const;

Return a const reverse iterator pointing to the beginning of the reversed circular buffer.


              reverse_iterator rbegin();

Return a reverse iterator pointing to the beginning of the reversed circular buffer.


              const_reverse_iterator rend() const;

Return a const reverse iterator pointing to the end of the reversed circular buffer.


              reverse_iterator rend();

Return a reverse iterator pointing to the end of the reversed circular buffer.


              iterator rerase(iterator first, iterator last);

Erase the range [first, last).

Precondition: Valid range [first, last). size_type old_size = (*this).size()

Postcondition: (*this).size() == old_size - std::distance(first, last)
Removes the elements from the range [first, last).

Returns: iterator to the first element remaining in front of the removed element or (*this).begin() if no such element exists.

Note:

For iterator invalidation see the documentation.


              iterator rerase(iterator pos);

Erase the element at the given position.

Precondition: Valid pos iterator. size_type old_size = (*this).size()

Postcondition: (*this).size() == old_size - 1
Removes an element at the position pos.

Returns: iterator to the first element remaining in front of the removed element or (*this).begin() if no such element exists.

Note:

For iterator invalidation see the documentation.


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

Change the size of the circular buffer.

Postcondition: (*this).size() == new_size
If the new size is greater than the current size, the rest of the circular buffer is filled with copies of item. In case the resulting size exceeds the current capacity the capacity is set to new_size. If the new size is lower than the current size then ((*this).size() - new_size) elements will be removed according to the remove_front parameter.

Note:

For iterator invalidation see the documentation.


              
      template <class InputIterator>
   
    void rinsert(iterator pos, InputIterator first, InputIterator last);

Insert the range [first, last) before the given position.

Precondition: Valid pos iterator and valid range [first, last).

Postcondition: This operation preserves the capacity of the circular buffer. If the insertion would result in exceeding the capacity of the circular buffer then the necessary number of elements from the end (right) of the circular buffer will be removed or not the whole range will be inserted or both. In case the whole range cannot be inserted it will be inserted just some elements from the beginning (left) of the range (see the example).Example: array to insert: int array[] = { 5, 6, 7, 8, 9 }; original circular buffer |1|2|3|4| | | - capacity: 6, size: 4 position ---------------------^ insert(position, array, array + 5); (If the operation won't preserve capacity, the buffer would look like this |1|2|5|6|7|8|9|3|4|) RESULTING circular buffer |1|2|5|6|7|8| - capacity: 6, size: 6

Note:

For iterator invalidation see the documentation.


              void rinsert(iterator pos, size_type n, value_type item);

Insert n copies of the item before the given position.

Precondition: Valid pos iterator.

Postcondition: This operation preserves the capacity of the circular buffer. If the insertion would result in exceeding the capacity of the circular buffer then the necessary number of elements from the end (right) of the circular buffer will be removed or not all n elements will be inserted or both.Example: original circular buffer |1|2|3|4| | | - capacity: 6, size: 4 position ---------------------^ insert(position, (size_t)5, 6); (If the operation won't preserve capacity, the buffer would look like this |1|2|6|6|6|6|6|3|4|) RESULTING circular buffer |1|2|6|6|6|6| - capacity: 6, size: 6

Note:

For iterator invalidation see the documentation.


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

Insert an item before the given position.

Precondition: Valid pos iterator.

Postcondition: The item will be inserted before the position pos.
If the circular buffer is full, the last element (rightmost) will be removed.

Returns:

iterator to the inserted element.

Note:

For iterator invalidation see the documentation.


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

TODO doc.


              void rset_capacity(size_type new_capacity);

TODO doc.


              void set_capacity(size_type new_capacity);

Change the capacity of the circular buffer.

Postcondition: (*this).capacity() == new_capacity
If the current number of elements stored in the circular buffer is greater than the desired new capacity then ((*this).size() - new_capacity) elements will be removed according to the remove_front parameter.

Note:

For iterator invalidation see the documentation.


              size_type size() const;

Return the number of elements currently stored in the circular buffer.


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

Swap the contents of two circular buffers.

Postcondition: this contains elements of cb and vice versa.

Note:

For iterator invalidation see the documentation.

Standalone Functions

Semantics

The rules for iterator (and result of


                    data()

) invalidation for


                    circular_buffer

are as follows:

In addition to the preceding rules the iterators get also invalidated due to overwriting (e.g. iterator pointing to the front-most element gets invalidated when inserting into the full


                    circular_buffer

). They get invalidated in that sense they do not point to the same element as before but they do still point to the same valid place in the memory. If you want to rely on this feature you have to turn of the Debug Support otherwise an assertion will report an error if such invalidated iterator is used.

Caveats

The


                    circular_buffer

should not be used for storing pointers to dynamically allocated objects. When a


                    circular_buffer

becomes full, further insertion will overwrite the stored pointers - resulting in a memoryleak. One recommend alternative is the use of smart pointers [2]. (Any container of


                    std::auto_ptr

is considered particularly hazardous. [3] )

Elements inserted near the front of a full


                    circular_buffer

can be lost. According to the semantics of


                    insert

, insertion overwrites front-most items as necessary - possibly including elements currently being inserted at the front of the buffer. Conversely,


                    push_front

to a full


                    circular_buffer

is guaranteed to overwrite the back-most element.

Elements inserted near the back of a full


                    circular_buffer

can be lost. According to the semantics of


                    rinsert

, insertion overwrites front-most items as necessary - possibly including elements currently being inserted at the back of the buffer. Conversely,


                    push_back

to a full


                    circular_buffer

is guaranteed to overwrite the front-most element.

While internals of a


                    circular_buffer

are circular, iterators are not. Iterators of a


                    circular_buffer

are only valid for the range


                    [begin(),
                    end()]

. E.g. iterators


                    (begin() - 1)

and


                    (end() + 1)

are invalid.

Debug Support

In order to help a programmer to avoid and find common bugs, the


                    circular_buffer

contains a kind of debug support.

The


                    circular_buffer

maintains a list of valid iterators. As soon as any element gets destroyed all iterators pointing to this element are removed from this list and explicitly invalidated (an invalidation flag is set). The debug support also consists of many assertions (


                        BOOST_ASSERT

macros) which ensure the


                    circular_buffer

and its iterators are used in the correct manner at runtime. In case an invalid iterator is used the assertion will report an error. The connection of explicit iterator invalidation and assertions makes a very robust debug technique which catches most of the errors.

Moreover, the uninitialized memory allocated by


                    circular_buffer

is filled with the value


                    0xcc

in the debug mode. This can help the programmer when debugging the code to recognize the initialized memory from the uninitialized. For details refer the source code.

The debug support is enabled only in the debug mode (when the


                    NDEBUG

is not defined). It can also be explicitly disabled by defining


                    BOOST_CB_DISABLE_DEBUG

macro.

Example

The


                    circular_buffer

has a capacity of three

int

. Therefore, the size of the buffer will not exceed three. The


                    accumulate

algorithm evaluates the sum of the stored elements. The semantics of the


                    circular_buffer

can be inferred from the assertions.

Notes

[3] Never create a circular buffer of


                    std::auto_ptr

. Refer to Scott Meyers ' excellent book Effective STL for a detailed discussion. (Meyers S., Effective STL: 50 SpecificWays to Improve Your Use of the Standard Template Library. Addison-Wesley, 2001.)

Templated Circular Buffer Container

circular_buffer<T, Alloc>

Contents

Description

Simple Example

Rationale

Thread-Safety

Writing to a Full Buffer

Reading from an Empty Buffer

Iterator Invalidation

Overwrite Operation

Producer-Consumer Mode

Synopsis

Header Files

Modeled Concepts

Template Parameters

Public Types

Constructors and Destructor

Public Member Functions

Standalone Functions

Semantics

Caveats

Debug Support

Example

Notes

See also

Acknowledgments