mirror of
https://github.com/boostorg/circular_buffer.git
synced 2026-01-26 06:22:30 +00:00
197 lines
8.9 KiB
HTML
197 lines
8.9 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Space Optimized Circular Buffer Container Adaptor</title>
|
|
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
|
|
</head>
|
|
<body bgColor="#ffffff">
|
|
<h1>Space Optimized Circular Buffer Container Adaptor</h1>
|
|
<table id="title" border="0">
|
|
<tr>
|
|
<td>
|
|
<h1>circular_buffer_space_optimized<T, Alloc></h1>
|
|
</td>
|
|
<td><a href="http://boost.org"><IMG height="86" src="../../../c++boost.gif" width="277" border="0" alt="Boost"></a></td>
|
|
</tr>
|
|
</table>
|
|
<h3>Contents</h3>
|
|
<dl><dd><A href="#description">Description</A></dd>
|
|
<dd><A href="#synopsis">Synopsis</A></dd>
|
|
<dd><A href="#rationale">Rationale</A></dd>
|
|
<dd><A href="#header">Header files</A></dd>
|
|
<dd><A href="#model">Modeled concepts</A></dd>
|
|
<dd><A href="#members">Template Parameters, Members and Standalone
|
|
Functions</A></dd>
|
|
<dd><A href="#semantics">Semantics</A></dd>
|
|
<dd><A href="#see">See also</A></dd>
|
|
<dd><A href="#ack">Acknowledgments</A></dd>
|
|
</dl>
|
|
<h3><a name="description">Description</a></h3>
|
|
<p>The <code>circular_buffer_space_optimized</code> container is an adaptor of the <CODE>
|
|
<A href="circular_buffer.html">circular_buffer</A></CODE>. The
|
|
functionality of the <CODE>circular_buffer_space_optimized</CODE> is similar to
|
|
the base <code>circular_buffer</code> except it does not allocate memory at
|
|
once when created rather it allocates memory as needed. (The predictive memory
|
|
allocation is similar to typical <code>std::vector</code> implementation.)
|
|
Moreover the memory is automatically freed as the size of the container
|
|
decreases.
|
|
</p>
|
|
<table id="figure" border="0">
|
|
<tr>
|
|
<td></td>
|
|
<td><IMG height="350" src="circular_buffer_space_optimized.png" width="700" alt="Space Optimized Circular Buffer"></td>
|
|
</tr>
|
|
<tr>
|
|
<td vAlign="top"><b>Figure:</b></td>
|
|
<td vAlign="top">The memory allocation process of the space optimized circular
|
|
buffer. The <code>min_capacity</code> represents the minimal guaranteed amount
|
|
of allocated memory. The allocated memory will never drop under this value. By
|
|
default the <code>min_capacity</code> is set to 0.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<h3><a name="synopsis">Synopsis</a></h3>
|
|
<div id="srcdoc_synopsis"></div>
|
|
<h3><a name="rationale">Rationale</a></h3>
|
|
<p>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 <code>circular_buffer_space_optimized</code>
|
|
will result in decreased memory consumption and can improve the CPU cache
|
|
effectiveness.
|
|
</p>
|
|
<h3><a name="header">Header files</a></h3>
|
|
<P>
|
|
The <code>circular_buffer_space_optimized</code> is defined in the file
|
|
<code><A href="../../../boost/circular_buffer.hpp">boost/circular_buffer.hpp</A></code>.
|
|
There is also a forward declaration for the <code>circular_buffer_space_optimized</code> in the header file
|
|
<code><A href="../../../boost/circular_buffer_fwd.hpp">boost/circular_buffer_fwd.hpp</A></code>.
|
|
</P>
|
|
<h3><a name="model">Modeled concepts</a></h3>
|
|
<p><a href="http://www.sgi.com/tech/stl/RandomAccessContainer.html">Random Access
|
|
Container</a>, <a href="http://www.sgi.com/tech/stl/FrontInsertionSequence.html">
|
|
Front Insertion Sequence</a>, <a href="http://www.sgi.com/tech/stl/BackInsertionSequence.html">
|
|
Back Insertion Sequence</a>, <a href="http://www.sgi.com/tech/stl/Assignable.html">
|
|
Assignable</a> (SGI specific), <a href="http://www.sgi.com/tech/stl/EqualityComparable.html">
|
|
Equality Comparable</a>, <a href="http://www.sgi.com/tech/stl/LessThanComparable.html">
|
|
LessThan Comparable</a> (SGI specific)
|
|
</p>
|
|
<h3><a name="members">Template Parameters, Members and Friend Functions</a></h3>
|
|
<p>Template parameters, members and friend functions of the <code>circular_buffer_space_optimized</code>
|
|
are almost the same as for the base <code>circular_buffer</code>. Refer the <code>circular_buffer</code>
|
|
<A href="circular_buffer.html#parameters">documentation</A> and also its <A href="srcdoc/index.html">
|
|
source code documentation</A> for a detailed description.
|
|
</p>
|
|
<p>The specific methods of the <code>circular_buffer_space_optimized</code> are
|
|
listed below.
|
|
</p>
|
|
<table id="members_perations" width="85%" border="1">
|
|
<tr>
|
|
<TH>
|
|
Method
|
|
</TH>
|
|
<TH>
|
|
Description
|
|
</TH>
|
|
</tr>
|
|
<tr>
|
|
<td><code><A href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a9">circular_buffer_space_optimized</A>(size_type
|
|
capacity, size_type min_capacity = 0, const allocator_type& alloc =
|
|
allocator_type())</code>
|
|
</td>
|
|
<td>Create an empty space optimized circular buffer with a given capacity.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><A href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a10">circular_buffer_space_optimized</A>
|
|
(size_type capacity, size_type min_capacity, const T& item, const
|
|
allocator_type& alloc = allocator_type())</code>
|
|
</td>
|
|
<td>Create a full space optimized circular buffer filled with copies of <code>item</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>template<InputIterator> <A href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a11">
|
|
circular_buffer_space_optimized</A>(size_type capacity, size_type
|
|
min_capacity, InputIterator first, InputIterator last, const
|
|
allocator_type& alloc = allocator_type())</code>
|
|
</td>
|
|
<td>Create a space optimized circular buffer with a copy of a range.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><A href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a3">min_capacity</A>()
|
|
const</code>
|
|
</td>
|
|
<td>Return the minimal guaranteed amount of allocated memory.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><A href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a4">set_min_capacity</A>()</code>
|
|
</td>
|
|
<td>Change the minimal guaranteed amount of allocated memory.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<h3><a name="semantics">Semantics</a></h3>
|
|
<p>The behaviour of memory auto-resizing is as follows:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
Minimal capacity is allocated when an empty <CODE>circular_buffer_space_optimized</CODE>
|
|
is created.
|
|
<LI>
|
|
When a non-empty <CODE>circular_buffer_space_optimized</CODE>
|
|
container is created the allocated memory reflects the size of the container.
|
|
<li>
|
|
<code>push_back</code>, <code>push_front</code>, <code>insert</code> and <code>rinsert</code>
|
|
will predictively increase the allocated memory if necessary. (The predictive
|
|
memory allocation is similar to <code>std::vector</code>.)
|
|
<LI>
|
|
<code>set_capacity</code>, <code>resize</code>, <code>assign</code>, <code>insert</code>
|
|
(range or n items), <code>rinsert</code> (range or n items), <code>erase</code>
|
|
(range) and <code>clear</code>
|
|
will accommodate the allocated memory as necessary.
|
|
<li>
|
|
<CODE>pop_back</CODE>, <CODE>pop_front</CODE>, <code>erase</code> and <code>clear</code>
|
|
will predictively decrease the allocated memory.
|
|
</li>
|
|
</ul>
|
|
<p>The semantics of the <code>circular_buffer_space_optimized</code> then follows
|
|
the <A href="circular_buffer.html#semantics">semantics</A> of the base <code>circular_buffer</code>
|
|
except the invalidation rules.
|
|
</p>
|
|
<p><a name="invalidation"></a>The rule for iterator invalidation for <code>circular_buffer_space_optimized</code>
|
|
is as follows:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<code>data</code>, <code>set_capacity</code>, <code>resize</code>, <code>operator=</code>,
|
|
<code>assign</code>, <code>swap</code>, <code>push_back</code>, <code>push_front</code>,
|
|
<code>pop_back</code>, <code>pop_front</code>, <code>insert</code>, <code>rinsert</code>,
|
|
<code>erase</code> and <code>clear</code> invalidate all iterators pointing to
|
|
the <code>circular_buffer_space_optimized</code>.
|
|
</li>
|
|
</ul>
|
|
<h3><a name="see">See also</a></h3>
|
|
<p><code><A href="circular_buffer.html">boost::circular_buffer</A>, <a href="http://www.sgi.com/tech/stl/Vector.html">
|
|
std::vector</a></code>
|
|
</p>
|
|
<h3><a name="ack">Acknowledgments</a></h3>
|
|
<p>The idea of the space optimized circular buffer has been introduced by Pavel
|
|
Vozenilek.
|
|
</p>
|
|
<hr align="left" size="1">
|
|
<table id="footer" border="0" width="100%">
|
|
<tr>
|
|
<td align="left" valign="top"><small>Copyright © 2003-2005 <a href="mailto:jano_gaspar%5Bat%5Dyahoo.com">Jan Gaspar</a></small></td>
|
|
<td align="right" valign="top">
|
|
<a href="http://validator.w3.org/check?url=http://www.boost.org/circular_buffer/libs/circular_buffer/doc/circular_buffer.html">
|
|
<img border="0" src="valid-html40.bmp" alt="Valid HTML 4.0!" height="31" width="88"></a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|