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=UTF-8"> 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 8. 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#idm45227213536240-bb">front()</a></code> or 151 <code class="computeroutput"><a class="link" href="../boost/circular_buffer.html#idm45227213033936-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#idm45227213352160-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#idm45227213559152-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"><</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">></span> 178<span class="preprocessor">#include</span> <span class="special"><</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">></span> 179<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">assert</span><span class="special">.</span><span class="identifier">h</span><span class="special">></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"><</span><span class="keyword">int</span><span class="special">></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"><</span><span class="keyword">int</span><span class="special">>::</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&)</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">&)</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">&</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">&</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">&)</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 © 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> 417
