Templated Circular Buffer Container

circular_buffer<T, Alloc>

   Synopsis
   Rationale
   Simple Example
   Definition
   Template Parameters
   Members
   Friend Functions
   Model of
   Type Requirements
   Semantics
   Caveats
   Debug Support
   Example
   Notes
   See also
   Acknowledgments

Figure:

The circular buffer (for someone known as ring or cyclic buffer).

Synopsis

The circular_buffer container provides fixed capacity storage with constant time insertion and removal of elements at each end of a circular buffer. When the capacity of the circular_buffer is exhausted, inserted elements will cause elements at the opposite end to be overwritten. (See the Figure.) 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_optimizedavailable. It is an adaptor of the circular_buffer which does not allocate memory at once when created rather it allocates memory as needed.)

Rationale

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

Fixed memory use and no implicit or unexpected memory allocation.
Fast constant-time insertion and removal of elements from the front and back.
Fast constant-time random access of elements.
Suitability for real-time and performance critical applications.

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.

Possible applications of the circular_buffer include:

Storage of the most recently received samples, overwriting the oldest as new samples arrive.
Efficient fixed capacity FIFO (First In, First Out) queue.
Efficient fixed capacity LIFO (Last In, First Out) queue.
In a producer-consumer arrangement elements are inserted at one end of the buffer by a producer thread, and removed from the other end by a consumer thread (both threads need to get synchronized in this).

The design of the circular_buffer container is guided by the following principles:

Maximum efficiency for envisaged applications.
Suitable for general purpose use.
Interoperable with other std containers and algorithms.
The behaviour of the buffer as intuitive as possible.
Suitable for specialization by means of adaptors. (The circular_buffer_space_optimized is such an example of the adaptor.)
Guarantee of basic exception safety.

Simple Example

A brief example using the circular_buffer:

   #include <boost/circular_buffer.hpp>

   int main(int argc, char* argv[]) {

      // Create a circular buffer with capacity for 3 integers.
      boost::circular_buffer<int> cb(3);

      cb.push_back(1);  // Insert the first element.
      cb.push_back(2);  // Insert the second element.
      cb.push_back(3);  // Insert the third element.

      // The buffer is full now, pushing subsequent
      // elements will overwrite the front-most elements.
      
      cb.push_back(4);  // Overwrite 1 with 4.
      cb.push_back(5);  // Overwrite 2 with 5.

      // The buffer now contains 3, 4 and 5.
      int a = cb[0];  // a == 3
      int b = cb[1];  // b == 4
      int c = cb[2];  // c == 5

      // Elements can be popped from either the front or back.

      cb.pop_back();  // 5 is removed.
      cb.pop_front(); // 3 is removed.

      int d = cb[0];  // d == 4

      return 0;
   }

Definition

#include <boost/circular_buffer.hpp>

In fact the circular_buffer is defined in the file boost/circular_buffer/base.hpp, but it is necessary to include the boost/circular_buffer.hpp in order to use this container. Also, there is a forward declaration for circular_buffer in the header boost/circular_buffer_fwd.hpp.

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`

Members

Refer the source code documentation for a detailed description.

Type	Description
`value_type`	The type of the elements stored in the circular buffer.
`allocator_type`	The type of the allocator used in the circular buffer.
`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.
`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. A signed integral type used to represent the distance between two iterators.
`size_type`	Size type. An unsigned integral type that can represent any nonnegative value of the container's distance type.

Method	Description
`circular_buffer(size_type capacity, const allocator_type& alloc = allocator_type())`	Create an empty circular buffer with a given capacity.
`circular_buffer(size_type capacity, const T& item, const allocator_type& alloc = allocator_type())`	Create a full circular buffer with a given capacity and filled with copies of `item`.
`circular_buffer(const circular_buffer& cb)`	Copy constructor.
`template<InputIterator> circular_buffer(size_type capacity, InputIterator first, InputIterator last, const allocator_type& alloc = allocator_type())`	Create a circular buffer with a copy of a range.
`~circular_buffer()`	Destructor.
`template<InputIterator> assign(InputIterator first, InputIterator last)`	Assign a copy of range.
`assign(size_type n, const T& item)`	Assign `n` items into the circular buffer.
`push_back()`	Insert a new element with the default value at the end.
`push_back(const T& item)`	Insert a new element at the end.
`push_front()`	Inserts a new element with the default value at the start.
`push_front(const T& item)`	Insert a new element at the start.
`pop_back()`	Remove the last (rightmost) element.
`pop_front()`	Remove the first (left-most) element.
`front()^*`	Return the first (leftmost) element.
`back()^*`	Return the last (rightmost) element.
`at(size_type index)^*`	Return the element at the `index` position.
`operator[](size_type index)^*`	Return the element at the `index` position.
`data()`	Return pointer to data stored in the circular buffer as a continuous array of values.
`insert(iterator pos)`	Insert a new element with the default value before the given position.
`insert(iterator pos, const T& item)`	Insert the `item` before the given position.
`insert(iterator pos, size_type n, const T& item)`	Insert `n` copies of the `item` before the given position.
`template<InputIterator> insert(iterator pos, InputIterator first, InputIterator last)`	Insert the range `[first, last)` before the given position.
`rinsert(iterator pos)`	Insert a new element with the default value before the given position.
`rinsert(iterator pos, const T& item)`	Insert the `item` before the given position.
`rinsert(iterator pos, size_type n, const T& item)`	Insert `n` copies of the `item` before the given position.
`template<InputIterator> rinsert(iterator pos, InputIterator first, InputIterator last)`	Insert the range `[first, last)` before the given position.
`erase(iterator pos)`	Erase the element at the given position.
`erase(iterator first, iterator last)`	Erase the range `[first, last)`.
`clear()`	Erase all the stored elements.
`empty() const`	Is the circular buffer empty?
`full() const`	Is the circular buffer full?
`size() const`	Return the number of elements currently stored in the circular buffer.
`resize(size_type new_size, param_value_type item = T(), bool remove_front = true)`	Change the size of the circular buffer.
`max_size() const`	Return the largest possible size (or capacity) of the circular buffer.
`capacity() const`	Return the capacity of the circular buffer.
`set_capacity(size_type new_capacity, bool remove_front = true)`	Change the capacity of the circular buffer.
`begin()^*`	Return an iterator pointing to the beginning of the circular buffer.
`end()^*`	Return an iterator pointing to the end of the circular buffer.
`rbegin()^*`	Return a reverse iterator pointing to the beginning of the reversed circular buffer.
`rend()^*`	Return a reverse iterator pointing to the end of the reversed circular buffer.
`get_allocator()^*`	Return the allocator.
`operator=(const circular_buffer& cb)`	Assignment operator.
`swap(circular_buffer& cb)`	Swap the contents of two circular buffers.

* The method also has its const counterpart.

Friend Functions

Method	Description
`operator<(const circular_buffer& lhs, const circular_buffer& rhs)`	Lexicographical comparison.
`operator==(const circular_buffer& lhs, const circular_buffer& rhs)`	Test two circular buffers for equality.

Model of

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

Type Requirements

T is CopyConstructible.

Semantics

The behaviour of insertion for circular_buffer is as follows:

The capacity of a circular_buffer remains fixed unless adjusted via set_capacity or resize.
insert will overwrite front elements as necessary.
rinsert will overwrite back elements as necessary.

The behaviour of resizing a circular_buffer is as follows:

The capacity will be adjusted to accommodate a resize. (The capacity can be only increased, not decreased.)

The behaviour of assigning to a circular_buffer is as follows:

The capacity will be adjusted to accommodate an assign. (The capacity can be only increased, not decreased.)

The rules for iterator (and result of data()) invalidation for circular_buffer are as follows:

insert at the end of the circular_buffer (including push_back) does not invalidate any iterator except the case the iterator points to the overwritten element.
rinsert at the beginning of the circular_buffer (including push_front) does not invalidate any iterator except the case the iterator points to the overwritten element.
insert in the middle of the circular_buffer invalidates iterators pointing to the elements at the insertion point and behind the insertion point. It also invalidates iterators pointing to the overwritten element(s).
rinsert in the middle of the circular_buffer invalidates iterators pointing to the elements before the insertion point and iterators pointing to the overwritten element(s).
erase at the end of the circular_buffer (including pop_back) invalidates only iterators pointing to the erased element(s).
pop_front invalidates only iterators pointing to the erased element.
erase at the beginning or in the middle of the circular_buffer invalidates iterators pointing to the erased element(s) and iterators pointing to the elements behind the erase point.
data, set_capacity, resize, operator=, assign, swap and clear invalidate all iterators pointing to the circular_buffer.

In addition to the preceding rules the iterators get also invalidated due to overwritting (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 memory leak. One recommend alternative is the use of smart pointers [1]. (Any container of std::auto_ptr is considered particularly hazardous. [2])

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_DISABLE_CB_DEBUG macro.

Example

The following example includes various usage of the circular_buffer.

   #include <boost/circular_buffer.hpp>
   #include <numeric>
   #include <assert.h>

   int main(int argc, char* argv[])
   {
      // create a circular buffer of capacity 3
      boost::circular_buffer<int> cb(3); 

      // insert some elements into the circular buffer
      cb.push_back(1);
      cb.push_back(2);

      // assertions
      assert(cb[0] == 1);
      assert(cb[1] == 2);
      assert(!cb.full());
      assert(cb.size() == 2);
      assert(cb.capacity() == 3);

      // insert some other elements
      cb.push_back(3);
      cb.push_back(4);
      int sum = std::accumulate(cb.begin(), cb.end(), 0); // evaluate sum

      // assertions
      assert(cb[0] == 2);
      assert(cb[1] == 3);
      assert(cb[2] == 4);
      assert(sum == 9);
      assert(cb.full());
      assert(cb.size() == 3);
      assert(cb.capacity() == 3);
      return 0;
   }

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 the circular_buffer can be inferred from the assertions.

Notes

[1] A good implementation of smart pointers is included in Boost.

[2] 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 Specific Ways to Improve Your Use of the Standard Template Library. Addison-Wesley, 2001.)

Acknowledgments

I would like to thank the Boost community for help when developing the circular_buffer.

The circular_buffer has a short history. Its first version was a std::deque adaptor. This container was not very effective because of many reallocations when inserting/removing an element. Thomas Wenish did a review of this version and motivated me to create a circular buffer which allocates memory at once when created.

The second version adapted std::vector but it has been abandoned soon because of limited control over iterator invalidation.

The current version is a full-fledged STL compliant container. Pavel Vozenilek did a thorough review of this version and came with many good ideas and improvements. Also, I would like to thank Howard Hinnant and Nigel Stewart for valuable comments and ideas. And once again I want to thank Nigel Stewart for this document revision.

Templated Circular Buffer Container

circular_buffer<T, Alloc>

Contents