Templated Circular Buffer Container

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

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;
   }

Synopsis

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.

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.

Header files

The circular_buffer is defined in the file boost/circular_buffer.hpp. There is also a forward declaration for the circular_buffer 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

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

Constructors / Destructor

Public Member Functions

Standalone Functions

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.