Templated Circular Buffer Container
circular_buffer<T, Alloc>
Templated Circular Buffer Containercircular_buffer<T, Alloc> |
|
 |
||
|
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_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.)
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;
}
namespace boost {
template <class T, class Alloc>
class circular_buffer
{
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(size_type capacity, InputIterator first, InputIterator last, const allocator_type& alloc = allocator_type());
circular_buffer(const circular_buffer<T,Alloc>& cb);
circular_buffer(size_type capacity, value_type item, const allocator_type& alloc = allocator_type());
explicit circular_buffer(size_type capacity, const allocator_type& alloc = allocator_type());
~circular_buffer();
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;
circular_buffer<T,Alloc>& operator=(const circular_buffer<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);
size_type size() const;
void swap(circular_buffer& cb);
};
template <class T, class Alloc>
bool operator!=(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
template <class T, class Alloc>
bool operator<(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
template <class T, class Alloc>
bool operator<=(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
template <class T, class Alloc>
bool operator==(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
template <class T, class Alloc>
bool operator>(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
template <class T, class Alloc>
bool operator>=(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
template <class T, class Alloc>
void swap(circular_buffer<T,Alloc>& lhs, circular_buffer<T,Alloc>& rhs);
} // namespace boost
|
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.
Possible applications of the circular_buffer include:
The design of the circular_buffer container is guided by the
following principles:
std
containers and algorithms.
circular_buffer_space_optimized
is such an example of the adaptor.)
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.
Random Access Container, Front Insertion Sequence, Back Insertion Sequence, Assignable (SGI specific), Equality Comparable, LessThan Comparable (SGI specific)
| 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> |
The behaviour of insertion for circular_buffer is as follows:
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:
resize. (The
capacity can be only increased, not decreased.)
The behaviour of assigning to a circular_buffer is as follows:
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.
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.
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.
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);
// evaluate the sum
int sum = std::accumulate(cb.begin(), cb.end(), 0);
// 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 of the circular_buffer can be inferred from
the assertions.
[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.)
boost::circular_buffer_space_optimized,
std::vector,
std::list, std::deque
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.
| Copyright © 2003-2005 Jan Gaspar |
|