diff --git a/doc/circular_buffer.qbk b/doc/circular_buffer.qbk index 837d760..24f1678 100644 --- a/doc/circular_buffer.qbk +++ b/doc/circular_buffer.qbk @@ -334,9 +334,9 @@ so for example: iterators `(begin() - 1)` and `(end() + 1)` are both invalid. [h3 Debug Support] In order to help a programmer to avoid and find common bugs, -the __cb contains a kind of debug support. +the __cb can be enabled to provide a kind of debug support. -The __cb maintains a list of valid iterators. +When the debugging functionality is enabled, the __cb 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) @@ -349,9 +349,13 @@ Moreover, the uninitialized memory allocated by __cb is filled with the value `0 When debugging the code, this can help the programmer to recognize the initialized memory from the uninitialized. For details refer the source code [@boost:boost/circular_buffer/debug.hpp circular_buffer/debug.hpp]. -The debug support is enabled only in the debug mode (when the `NDEBUG` is not defined). -It can also be explicitly disabled (only for __cb) -by defining macro BOOST_CB_DISABLE_DEBUG. +[caution Since the debugging code makes __cb and its iterators more interconnected, thread safety guarantees of __cb +are different when debug support is enabled. In addition to the container itself, all iterators tracked by the container +(including any copies thereof) must be protected from concurrent access. In particular, this includes copying, destroying or +obtaining iterators from the container, even if for read-only access.] + +The debug support is disabled by default. To enable it, one has to define `BOOST_CB_ENABLE_DEBUG` macro with the value of 1 +while compiling the code using __cb. [h3 Compatibility with Interprocess library] @@ -360,7 +364,7 @@ The __cb is compatible with the [@boost:libs/interprocess/index.html Boost.Inte library used for interprocess communication. Considering that the circular_buffer's debug support relies on 'raw' pointers (which is not permited by the Interprocess library) -the code has to compiled with `-DBOOST_CB_DISABLE_DEBUG` or `-DNDEBUG` (which disables the Debug Support). +the code has to compiled with debug support disabled (i.e. with `BOOST_CB_ENABLE_DEBUG` macro not defined or defined to 0). Not doing that will cause the compilation to fail. [endsect] [/section:implementation Implementation ] diff --git a/example/bounded_buffer_comparison.cpp b/example/bounded_buffer_comparison.cpp index 2edf8fd..4205c3a 100644 --- a/example/bounded_buffer_comparison.cpp +++ b/example/bounded_buffer_comparison.cpp @@ -7,8 +7,6 @@ // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) -#define BOOST_CB_DISABLE_DEBUG - #include #include #include diff --git a/example/circular_buffer_iter_example.cpp b/example/circular_buffer_iter_example.cpp index 9cefffd..339d284 100644 --- a/example/circular_buffer_iter_example.cpp +++ b/example/circular_buffer_iter_example.cpp @@ -5,11 +5,13 @@ // (See the accompanying file LICENSE_1_0.txt // or a copy at .) +#undef BOOST_CB_ENABLE_DEBUG + //[circular_buffer_iter_example_1 /*` */ -#define BOOST_CB_DISABLE_DEBUG // The Debug Support has to be disabled, otherwise the code produces a runtime error. +#define BOOST_CB_ENABLE_DEBUG 0 // The Debug Support has to be disabled, otherwise the code produces a runtime error. #include #include @@ -34,5 +36,5 @@ int main(int /*argc*/, char* /*argv*/[]) return 0; } - - //] [/circular_buffer_iter_example_1] + +//] [/circular_buffer_iter_example_1] diff --git a/include/boost/circular_buffer.hpp b/include/boost/circular_buffer.hpp index f5eff60..7cf8928 100644 --- a/include/boost/circular_buffer.hpp +++ b/include/boost/circular_buffer.hpp @@ -20,10 +20,8 @@ #include // BOOST_CB_ENABLE_DEBUG: Debug support control. -#if defined(NDEBUG) || defined(BOOST_CB_DISABLE_DEBUG) +#if !defined(BOOST_CB_ENABLE_DEBUG) #define BOOST_CB_ENABLE_DEBUG 0 -#else - #define BOOST_CB_ENABLE_DEBUG 1 #endif // BOOST_CB_ASSERT: Runtime assertion. @@ -60,6 +58,5 @@ #undef BOOST_CB_ASSERT_TEMPLATED_ITERATOR_CONSTRUCTORS #undef BOOST_CB_IS_CONVERTIBLE #undef BOOST_CB_ASSERT -#undef BOOST_CB_ENABLE_DEBUG #endif // #if !defined(BOOST_CIRCULAR_BUFFER_HPP) diff --git a/include/boost/circular_buffer/space_optimized.hpp b/include/boost/circular_buffer/space_optimized.hpp index 688ab95..3d00173 100644 --- a/include/boost/circular_buffer/space_optimized.hpp +++ b/include/boost/circular_buffer/space_optimized.hpp @@ -740,7 +740,7 @@ public: \par Iterator Invalidation Invalidates all iterators of both circular_buffer_space_optimized containers. (On the other hand the iterators still point to the same elements but within another container. If you want to rely on - this feature you have to turn the __debug_support off by defining macro BOOST_CB_DISABLE_DEBUG, + this feature you have to turn the __debug_support off, otherwise an assertion will report an error if such invalidated iterator is used.) \par Complexity Constant (in the size of the circular_buffer_space_optimized). diff --git a/test/Jamfile.v2 b/test/Jamfile.v2 index a266864..7e1ae58 100644 --- a/test/Jamfile.v2 +++ b/test/Jamfile.v2 @@ -22,9 +22,11 @@ project ; test-suite "circular_buffer" - : [ run base_test.cpp : single : ] - [ run space_optimized_test.cpp : single : ] - [ run soft_iterator_invalidation.cpp : single : ] - [ run constant_erase_test.cpp : single : ] + : [ run base_test.cpp : : : single : ] + [ run space_optimized_test.cpp : : : single : ] + [ run base_test.cpp : : : single "BOOST_CB_ENABLE_DEBUG=1" : base_test_dbg ] + [ run space_optimized_test.cpp : : : single "BOOST_CB_ENABLE_DEBUG=1" : space_optimized_test_dbg ] + [ run soft_iterator_invalidation.cpp : : : single : ] + [ run constant_erase_test.cpp : : : single : ] [ compile bounded_buffer_comparison.cpp : multi : ] ; diff --git a/test/base_test.cpp b/test/base_test.cpp index 518d689..0a318ed 100644 --- a/test/base_test.cpp +++ b/test/base_test.cpp @@ -193,7 +193,7 @@ void iterator_comparison_test() { void iterator_invalidation_test() { -#if !defined(NDEBUG) && !defined(BOOST_CB_DISABLE_DEBUG) +#if BOOST_CB_ENABLE_DEBUG circular_buffer::iterator it1; circular_buffer::const_iterator it2; @@ -563,7 +563,7 @@ void iterator_invalidation_test() { BOOST_CHECK(it3.is_valid(&cb16)); BOOST_CHECK(!it4.is_valid(&cb16)); -#endif // #if !defined(NDEBUG) && !defined(BOOST_CB_DISABLE_DEBUG) +#endif // #if BOOST_CB_ENABLE_DEBUG } // basic exception safety test (it is useful to use any memory-leak detection tool) diff --git a/test/bounded_buffer_comparison.cpp b/test/bounded_buffer_comparison.cpp index 5e84c88..b31c8f8 100644 --- a/test/bounded_buffer_comparison.cpp +++ b/test/bounded_buffer_comparison.cpp @@ -7,8 +7,6 @@ // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) -#define BOOST_CB_DISABLE_DEBUG - #include #include #include diff --git a/test/constant_erase_test.cpp b/test/constant_erase_test.cpp index 32bb225..ba41f6c 100644 --- a/test/constant_erase_test.cpp +++ b/test/constant_erase_test.cpp @@ -6,8 +6,6 @@ // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) -#define BOOST_CB_DISABLE_DEBUG - #include "test.hpp" int MyInteger::ms_exception_trigger = 0; diff --git a/test/soft_iterator_invalidation.cpp b/test/soft_iterator_invalidation.cpp index 7d23971..770179d 100644 --- a/test/soft_iterator_invalidation.cpp +++ b/test/soft_iterator_invalidation.cpp @@ -9,8 +9,6 @@ // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) -#define BOOST_CB_DISABLE_DEBUG - #include "test.hpp" // test of the example (introduced in the documentation) diff --git a/test/space_optimized_test.cpp b/test/space_optimized_test.cpp index 393e5e5..3c708c9 100644 --- a/test/space_optimized_test.cpp +++ b/test/space_optimized_test.cpp @@ -125,7 +125,7 @@ void shrink_to_fit_test() { void iterator_invalidation_test() { -#if !defined(NDEBUG) && !defined(BOOST_CB_DISABLE_DEBUG) +#if BOOST_CB_ENABLE_DEBUG cb_space_optimized cb1(10, 1); cb1.push_back(2); @@ -177,7 +177,7 @@ void iterator_invalidation_test() { BOOST_CHECK(!it2.is_valid(&cb1)); BOOST_CHECK(!it3.is_valid(&cb1)); -#endif // #if !defined(NDEBUG) && !defined(BOOST_CB_DISABLE_DEBUG) +#endif // #if BOOST_CB_ENABLE_DEBUG } // test main