doc/html/circular_buffer/implementation.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Implementation</title>
   6 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="../circular_buffer.html" title="Chapter&#160;8.&#160;Boost.Circular Buffer">
  10 <link rel="prev" href="rationale.html" title="Rationale">
  11 <link rel="next" href="examples.html" title="More Examples">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
  16 <td align="center"><a href="../../../index.html">Home</a></td>
  17 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="rationale.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../circular_buffer.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="examples.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="section">
  27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  28 <a name="circular_buffer.implementation"></a><a class="link" href="implementation.html" title="Implementation">Implementation </a>
  29 </h2></div></div></div>
  30 <p>
  31       The following paragraphs describe issues that had to be considered during the
  32       implementation of the circular_buffer:
  33     </p>
  34 <h4>
  35 <a name="circular_buffer.implementation.h0"></a>
  36       <span class="phrase"><a name="circular_buffer.implementation.thread_safety"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.thread_safety">Thread-Safety</a>
  37     </h4>
  38 <p>
  39       The thread-safety of the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
  40       is the same as the thread-safety of containers in most STL implementations.
  41       This means the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
  42       is not fully thread-safe. The thread-safety is guaranteed only in the sense
  43       that simultaneous accesses to distinct instances of the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
  44       are safe, and simultaneous read accesses to a shared <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
  45       are safe.
  46     </p>
  47 <p>
  48       If multiple threads access a single <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>,
  49       and at least one of the threads may potentially write, then the user is responsible
  50       for ensuring mutual exclusion between the threads during the container accesses.
  51       The mutual exclusion between the threads can be achieved by wrapping operations
  52       of the underlying <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
  53       with a lock acquisition and release. (See the Bounded Buffer example code at
  54       <a href="../../../libs/circular_buffer/example/circular_buffer_bound_example.cpp" target="_top">circular_buffer_bound_example.cpp</a>)
  55     </p>
  56 <h4>
  57 <a name="circular_buffer.implementation.h1"></a>
  58       <span class="phrase"><a name="circular_buffer.implementation.overwrite_operation"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.overwrite_operation">Overwrite
  59       Operation</a>
  60     </h4>
  61 <p>
  62       Overwrite operation occurs when an element is inserted into a full <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> - the old element
  63       is being overwritten by the new one. There was a discussion what exactly "overwriting
  64       of an element" means during the formal review. It may be either a destruction
  65       of the original element and a consequent inplace construction of a new element
  66       or it may be an assignment of a new element into an old one. The <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> implements assignment
  67       because it is more effective.
  68     </p>
  69 <p>
  70       From the point of business logic of a stored element, the destruction/construction
  71       operation and assignment usually mean the same. However, in very rare cases
  72       (if in any) they may differ. If there is a requirement for elements to be destructed/constructed
  73       instead of being assigned, consider implementing a wrapper of the element which
  74       would implement the assign operator, and store the wrappers instead. It is
  75       necessary to note that storing such wrappers has a drawback. The destruction/construction
  76       will be invoked on every assignment of the wrapper - not only when a wrapper
  77       is being overwritten (when the buffer is full) but also when the stored wrappers
  78       are being shifted (e.g. as a result of insertion into the middle of container).
  79     </p>
  80 <h4>
  81 <a name="circular_buffer.implementation.h2"></a>
  82       <span class="phrase"><a name="circular_buffer.implementation.writing_to_a_full_buffer"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.writing_to_a_full_buffer">Writing to
  83       a Full Buffer</a>
  84     </h4>
  85 <p>
  86       There are several options how to cope if a data source produces more data than
  87       can fit in the fixed-sized buffer:
  88     </p>
  89 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  90 <li class="listitem">
  91           Inform the data source to wait until there is room in the buffer (e.g.
  92           by throwing an overflow exception).
  93         </li>
  94 <li class="listitem">
  95           If the oldest data is the most important, ignore new data from the source
  96           until there is room in the buffer again.
  97         </li>
  98 <li class="listitem">
  99           If the latest data is the most important, write over the oldest data.
 100         </li>
 101 <li class="listitem">
 102           Let the producer to be responsible for checking the size of the buffer
 103           prior writing into it.
 104         </li>
 105 </ul></div>
 106 <p>
 107       It is apparent that the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 108       implements the third option. But it may be less apparent it does not implement
 109       any other option - especially the first two. One can get an impression that
 110       the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> should
 111       implement first three options and offer a mechanism of choosing among them.
 112       This impression is wrong.
 113     </p>
 114 <p>
 115       The <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> was
 116       designed and optimized to be circular (which means overwriting the oldest data
 117       when full). If such a controlling mechanism had been enabled, it would just
 118       complicate the matters and the usage of the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 119       would be probably less straightforward.
 120     </p>
 121 <p>
 122       Moreover, the first two options (and the fourth option as well) do not require
 123       the buffer to be circular at all. If there is a need for the first or second
 124       option, consider implementing an adaptor of e.g. std::vector. In this case
 125       the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> is
 126       not suitable for adapting, because, contrary to std::vector, it bears an overhead
 127       for its circular behaviour.
 128     </p>
 129 <h4>
 130 <a name="circular_buffer.implementation.h3"></a>
 131       <span class="phrase"><a name="circular_buffer.implementation.reading_removing_from_an_empty_b"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.reading_removing_from_an_empty_b">Reading/Removing
 132       from an Empty Buffer</a>
 133     </h4>
 134 <p>
 135       When reading or removing an element from an empty buffer, the buffer should
 136       be able to notify the data consumer (e.g. by throwing underflow exception)
 137       that there are no elements stored in it. The <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 138       does not implement such a behaviour for two reasons:
 139     </p>
 140 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 141 <li class="listitem">
 142           It would introduce a performance overhead.
 143         </li>
 144 <li class="listitem">
 145           No other std container implements it this way.
 146         </li>
 147 </ul></div>
 148 <p>
 149       It is considered to be a bug to read or remove an element (e.g. by calling
 150       <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html#idm46495625206000-bb">front()</a></code> or
 151       <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html#idm46495624703696-bb">pop_back()</a></code>)
 152       from an empty std container and from an empty <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 153       as well. The data consumer has to test if the container is not empty before
 154       reading/removing from it by testing <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html#idm46495625021920-bb">empty()</a></code>.
 155       However, when reading from the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>,
 156       there is an option to rely on the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html#idm46495625228912-bb">at()</a></code>
 157       method which throws an exception when the index is out of range.
 158     </p>
 159 <h4>
 160 <a name="circular_buffer.implementation.h4"></a>
 161       <span class="phrase"><a name="circular_buffer.implementation.iterator_invalidation"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.iterator_invalidation">Iterator
 162       Invalidation</a>
 163     </h4>
 164 <p>
 165       An iterator is usually considered to be invalidated if an element, the iterator
 166       pointed to, had been removed or overwritten by an another element. This definition
 167       is enforced by the Debug Support and is documented for every method. However,
 168       some applications utilizing <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 169       may require less strict definition: an iterator is invalid only if it points
 170       to an uninitialized memory.
 171     </p>
 172 <p>
 173       Consider following example:
 174     </p>
 175 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_CB_ENABLE_DEBUG</span> <span class="number">0</span> <span class="comment">// The Debug Support has to be disabled, otherwise the code produces a runtime error.</span>
 176
 177 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">circular_buffer</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 178 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">assert</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 179 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">assert</span><span class="special">.</span><span class="identifier">h</span><span class="special">&gt;</span>
 180
 181 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="comment">/*argc*/</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="comment">/*argv*/</span><span class="special">[])</span>
 182 <span class="special">{</span>
 183
 184   <span class="identifier">boost</span><span class="special">::</span><span class="identifier">circular_buffer</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">cb</span><span class="special">(</span><span class="number">3</span><span class="special">);</span>
 185
 186   <span class="identifier">cb</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">1</span><span class="special">);</span>
 187   <span class="identifier">cb</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
 188   <span class="identifier">cb</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">3</span><span class="special">);</span>
 189
 190   <span class="identifier">boost</span><span class="special">::</span><span class="identifier">circular_buffer</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">cb</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span>
 191
 192   <span class="identifier">assert</span><span class="special">(*</span><span class="identifier">it</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span>
 193
 194   <span class="identifier">cb</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
 195
 196   <span class="identifier">assert</span><span class="special">(*</span><span class="identifier">it</span> <span class="special">==</span> <span class="number">4</span><span class="special">);</span> <span class="comment">// The iterator still points to the initialized memory.</span>
 197
 198   <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 199 <span class="special">}</span>
 200 </pre>
 201 <p>
 202       The iterator does not point to the original element any more (and is considered
 203       to be invalid from the "strict" point of view) but it still points
 204       to the same valid place in the memory. This "soft" definition of
 205       iterator invalidation is supported by the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 206       but should be considered as an implementation detail rather than a full-fledged
 207       feature. The rules when the iterator is still valid can be inferred from the
 208       code in <a href="../../../libs/circular_buffer/test/soft_iterator_invalidation.cpp" target="_top">soft_iterator_invalidation.cpp</a>.
 209     </p>
 210 <h4>
 211 <a name="circular_buffer.implementation.h5"></a>
 212       <span class="phrase"><a name="circular_buffer.implementation.move_emulation_and_rvalues"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.move_emulation_and_rvalues">Move emulation
 213       and rvalues</a>
 214     </h4>
 215 <p>
 216       Since Boost 1.54.0 support for move semantics was implemented using the <a href="../../../libs/move/index.html" target="_top">Boost.Move</a> library. If rvalue references
 217       are available <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 218       will use them, but if not it uses a close, but imperfect emulation. On such
 219       compilers:
 220     </p>
 221 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 222 <li class="listitem">
 223           Non-copyable objects can be stored in the containers. They can be constructed
 224           in place using <code class="computeroutput"><span class="identifier">emplace</span></code>,
 225           or if they support Boost.Move, moved into place.
 226         </li>
 227 <li class="listitem">
 228           The containers themselves are not movable.
 229         </li>
 230 <li class="listitem">
 231           Argument forwarding is not perfect.
 232         </li>
 233 </ul></div>
 234 <p>
 235       <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> will use
 236       rvalues and move emulations for value types only if move constructor and move
 237       assignment operator of the value type do not throw; or if the value type has
 238       no copy constructor.
 239     </p>
 240 <p>
 241       Some methods won't use move constructor for the value type at all, if the constructor
 242       throws. This is required for data consistency and avoidance of situations,
 243       when aftrer an exception <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 244       contains moved away objects along with the good ones.
 245     </p>
 246 <p>
 247       See documentation for <a href="../../../libs/type_traits/doc/html/boost_typetraits/reference/is_copy_constructible.html" target="_top"><code class="computeroutput"><span class="identifier">is_copy_constructible</span></code></a>, <a href="../../../libs/type_traits/doc/html/boost_typetraits/reference/is_nothrow_move_assignable.html" target="_top"><code class="computeroutput"><span class="identifier">is_nothrow_move_assignable</span></code></a> and <a href="../../../libs/type_traits/doc/html/boost_typetraits/reference/is_nothrow_move_constructible.html" target="_top"><code class="computeroutput"><span class="identifier">is_nothrow_move_constructible</span></code></a> type
 248       triats. There you'll find information about how to make constructor of class
 249       noexcept and how to make a non-copyable class in C++03 and C++98.
 250     </p>
 251 <p>
 252       Performance of <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 253       will <span class="bold"><strong>greatly improve</strong></span> if value type has noexcept
 254       move constructor and noexcept move assignment.
 255     </p>
 256 <h4>
 257 <a name="circular_buffer.implementation.h6"></a>
 258       <span class="phrase"><a name="circular_buffer.implementation.exceptions_of_move_if_noexcept_t"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions
 259       of move_if_noexcept(T&amp;)</a>
 260     </h4>
 261 <p>
 262       Reference documentation of the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 263       contains notes like "Throws: See Exceptions of <code class="computeroutput"><span class="identifier">move_if_noexcept</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span></code>".
 264       That note means the following: <code class="computeroutput"><span class="identifier">move_if_noexcept</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;</span>
 265       <span class="identifier">value</span><span class="special">)</span></code>
 266       does not throws exceptions at all, but it returns <code class="computeroutput"><span class="identifier">value</span></code>
 267       as rvalue reference only if class <code class="computeroutput"><span class="identifier">T</span></code>
 268       have noexcept move constructor and noexcept move assignment operator; or if
 269       it has no copy constructor. Otherwise <code class="computeroutput"><span class="identifier">move_if_noexcept</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;</span>
 270       <span class="identifier">value</span><span class="special">)</span></code>
 271       returns <code class="computeroutput"><span class="identifier">value</span></code> as const reference.
 272     </p>
 273 <p>
 274       This leads us to the following situation:
 275     </p>
 276 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 277 <li class="listitem">
 278           If <code class="computeroutput"><span class="identifier">value</span></code> has a noexcept
 279           move constructor and noexcept move assignment operator, then no exceptions
 280           will be thrown at all.
 281         </li>
 282 <li class="listitem">
 283           If <code class="computeroutput"><span class="identifier">value</span></code> has a throwing
 284           move constructor and some copy constructor, then method may throw exceptions
 285           of copy constructor.
 286         </li>
 287 <li class="listitem">
 288           If <code class="computeroutput"><span class="identifier">value</span></code> has no copy constructor,
 289           then method may throw exceptions of move constructor.
 290         </li>
 291 </ul></div>
 292 <p>
 293       <code class="computeroutput"><span class="identifier">move_if_noexcept</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span></code> uses
 294       <a href="../../../libs/move/index.html" target="_top">Boost.Move</a>, <a href="../../../libs/type_traits/doc/html/boost_typetraits/reference/is_copy_constructible.html" target="_top"><code class="computeroutput"><span class="identifier">is_copy_constructible</span></code></a>, <a href="../../../libs/type_traits/doc/html/boost_typetraits/reference/is_nothrow_move_assignable.html" target="_top"><code class="computeroutput"><span class="identifier">is_nothrow_move_assignable</span></code></a> and <a href="../../../libs/type_traits/doc/html/boost_typetraits/reference/is_nothrow_move_constructible.html" target="_top"><code class="computeroutput"><span class="identifier">is_nothrow_move_constructible</span></code></a> type
 295       triats.
 296     </p>
 297 <h4>
 298 <a name="circular_buffer.implementation.h7"></a>
 299       <span class="phrase"><a name="circular_buffer.implementation.caveats"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.caveats">Caveats</a>
 300     </h4>
 301 <p>
 302       The <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> should
 303       not be used for storing pointers to dynamically allocated objects. When a circular
 304       buffer becomes full, further insertion will overwrite the stored pointers -
 305       resulting in a <span class="bold"><strong>memory leak</strong></span>. One recommend
 306       alternative is the use of smart pointers, for example <a href="http://www.boost.org/doc/libs/1_53_0/libs/smart_ptr/smart_ptr.htm" target="_top">Boost
 307       Smart pointers</a>.
 308     </p>
 309 <p>
 310       <a href="http://en.wikipedia.org/wiki/Std::auto_ptr" target="_top">std::auto_ptr</a>
 311     </p>
 312 <div class="caution"><table border="0" summary="Caution">
 313 <tr>
 314 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../doc/src/images/caution.png"></td>
 315 <th align="left">Caution</th>
 316 </tr>
 317 <tr><td align="left" valign="top"><p>
 318         Any container of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">auto_ptr</span></code> is considered particularly hazardous.
 319       </p></td></tr>
 320 </table></div>
 321 <div class="tip"><table border="0" summary="Tip">
 322 <tr>
 323 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../doc/src/images/tip.png"></td>
 324 <th align="left">Tip</th>
 325 </tr>
 326 <tr><td align="left" valign="top"><p>
 327         Never create a circular buffer of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">auto_ptr</span></code>.
 328         Refer to Scott Meyers' excellent book Effective STL for a detailed discussion.
 329         (Meyers S., Effective STL: 50 Specific Ways to Improve Your Use of the Standard
 330         Template Library. Addison-Wesley, 2001.)
 331       </p></td></tr>
 332 </table></div>
 333 <p>
 334       While internals of a <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 335       are circular, <span class="bold"><strong>iterators are not</strong></span>. Iterators
 336       of a <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> are
 337       only valid for the range <code class="computeroutput"><span class="special">\[</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">end</span><span class="special">()\]</span></code>,
 338       so for example: iterators <code class="computeroutput"><span class="special">(</span><span class="identifier">begin</span><span class="special">()</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span></code> and <code class="computeroutput"><span class="special">(</span><span class="identifier">end</span><span class="special">()</span> <span class="special">+</span>
 339       <span class="number">1</span><span class="special">)</span></code> are
 340       both invalid.
 341     </p>
 342 <h4>
 343 <a name="circular_buffer.implementation.h8"></a>
 344       <span class="phrase"><a name="circular_buffer.implementation.debug_support"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.debug_support">Debug
 345       Support</a>
 346     </h4>
 347 <p>
 348       In order to help a programmer to avoid and find common bugs, the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> can be enabled to
 349       provide a kind of debug support.
 350     </p>
 351 <p>
 352       When the debugging functionality is enabled, the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 353       maintains a list of valid iterators. As soon as any element gets destroyed
 354       all iterators pointing to this element are removed from this list and explicitly
 355       invalidated (an invalidation flag is set). The debug support also consists
 356       of many assertions (<code class="computeroutput"><span class="identifier">BOOST_ASSERT</span></code>
 357       macros) which ensure the <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 358       and its iterators are used in the correct manner at runtime. In case an invalid
 359       iterator is used, the assertion will report an error. The connection of explicit
 360       iterator invalidation and assertions makes a very robust debug technique which
 361       catches most of the errors.
 362     </p>
 363 <p>
 364       Moreover, the uninitialized memory allocated by <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 365       is filled with the value <code class="computeroutput"><span class="number">0xcc</span></code> in
 366       the debug mode. When debugging the code, this can help the programmer to recognize
 367       the initialized memory from the uninitialized. For details refer the source
 368       code <a href="../../../boost/circular_buffer/debug.hpp" target="_top">circular_buffer/debug.hpp</a>.
 369     </p>
 370 <div class="caution"><table border="0" summary="Caution">
 371 <tr>
 372 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../doc/src/images/caution.png"></td>
 373 <th align="left">Caution</th>
 374 </tr>
 375 <tr><td align="left" valign="top"><p>
 376         Since the debugging code makes <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 377         and its iterators more interconnected, thread safety guarantees of <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> are different when
 378         debug support is enabled. In addition to the container itself, all iterators
 379         tracked by the container (including any copies thereof) must be protected
 380         from concurrent access. In particular, this includes copying, destroying
 381         or obtaining iterators from the container, even if for read-only access.
 382       </p></td></tr>
 383 </table></div>
 384 <p>
 385       The debug support is disabled by default. To enable it, one has to define
 386       <code class="computeroutput"><span class="identifier">BOOST_CB_ENABLE_DEBUG</span></code> macro
 387       with the value of 1 while compiling the code using <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>.
 388     </p>
 389 <h4>
 390 <a name="circular_buffer.implementation.h9"></a>
 391       <span class="phrase"><a name="circular_buffer.implementation.compatibility_with_interprocess_"></a></span><a class="link" href="implementation.html#circular_buffer.implementation.compatibility_with_interprocess_">Compatibility
 392       with Interprocess library</a>
 393     </h4>
 394 <p>
 395       The <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> is
 396       compatible with the <a href="../../../libs/interprocess/index.html" target="_top">Boost.Interprocess</a>
 397       library used for interprocess communication. Considering that the circular_buffer's
 398       debug support relies on 'raw' pointers (which is not permitted by the Interprocess
 399       library) the code has to compiled with debug support disabled (i.e. with <code class="computeroutput"><span class="identifier">BOOST_CB_ENABLE_DEBUG</span></code> macro not defined or
 400       defined to 0). Not doing that will cause the compilation to fail.
 401     </p>
 402 </div>
 403 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 404 <td align="left"></td>
 405 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2013 Jan Gaspar<p>
 406         Distributed under the Boost Software License, Version 1.0. (See accompanying
 407         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 408       </p>
 409 </div></td>
 410 </tr></table>
 411 <hr>
 412 <div class="spirit-nav">
 413 <a accesskey="p" href="rationale.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../circular_buffer.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="examples.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 414 </div>
 415 </body>
 416 </html>