Inicio Explorar Axuda
Rexistro Iniciar sesión
devn00b
/
EQ2EMu
9
3
Fork 0
Ficheiros Incidencias 69 Pull Requests 0 Wiki
Árbore: 65109b0d5d
Ramas Etiquetas
EQ2EMu
/
EQ2
/
source
/
depends
/
boost_1_72_0
/
libs
/
multi_index
/
doc
/
tutorial
/
debug.html

debug.html 13 KB
Histórico Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252 
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0.1 Transitional//EN">
    2. 

  2. 

  3. <html>
    4. 

  4. <head>
    5. 

  5. <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    6. 

  6. <title>Boost.MultiIndex Documentation - Tutorial -Debugging support</title>
    7. 

  7. <link rel="stylesheet" href="../style.css" type="text/css">
    8. 

  8. <link rel="start" href="../index.html">
    9. 

  9. <link rel="prev" href="creation.html">
    10. 

  10. <link rel="up" href="index.html">
    11. 

  11. <link rel="next" href="techniques.html">
    12. 

  12. </head>
    13. 

  13. 

  14. <body>
    15. 

  15. <h1><img src="../../../../boost.png" alt="boost.png (6897 bytes)" align=
    16. 

  16. "middle" width="277" height="86">Boost.MultiIndex Tutorial: Debugging support</h1>
    17. 

  17. 

  18. <div class="prev_link"><a href="creation.html"><img src="../prev.gif" alt="container creation" border="0"><br>
    19. 

  19. Container creation
    20. 

  20. </a></div>
    21. 

  21. <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.MultiIndex tutorial" border="0"><br>
    22. 

  22. Boost.MultiIndex tutorial
    23. 

  23. </a></div>
    24. 

  24. <div class="next_link"><a href="techniques.html"><img src="../next.gif" alt="techniques" border="0"><br>
    25. 

  25. Techniques
    26. 

  26. </a></div><br clear="all" style="clear: all;">
    27. 

  27. 

  28. <hr>
    29. 

  29. 

  30. <h2>Contents</h2>
    31. 

  31. 

  32. <ul>
    33. 

  33.   <li><a href="#debugging_support">Debugging support</a></li>
    34. 

  34.   <li><a href="#safe_mode">Safe mode</a>
    35. 

  35.     <ul>
    36. 

  36.        <li><a href="#serialization_and_safe_mode">Serialization and safe mode</a></li>
    37. 

  37.     </ul>
    38. 

  38.   </li>
    39. 

  39.   <li><a href="#invariant_check">Invariant-checking mode</a></li>
    40. 

  40. </ul>
    41. 

  41. 

  42. <h2><a name="debugging_support">Debugging support</a></h2>
    43. 

  43. 

  44. <p>
    45. 

  45. The concept of <i>Design by Contract</i>, originally developed as part
    46. 

  46. of Bertrand Meyer's <a href="http://www.eiffel.com">Eiffel</a> language,
    47. 

  47. revolves around the formulation of a <i>contract</i> between the user
    48. 

  48. of a library and the implementor, by which the first is required to
    49. 

  49. respect some <i>preconditions</i> on the values passed when invoking
    50. 

  50. methods of the library, and the implementor guarantees in return
    51. 

  51. that certain constraints on the results are met (<i>postconditions</i>),
    52. 

  52. as well as the honoring of specified internal consistency rules, called
    53. 

  53. <i>invariants</i>. Eiffel natively supports the three parts of the
    54. 

  54. contract just described by means of constructs <code>require</code>,
    55. 

  55. <code>ensure</code> and <code>invariant</code>, respectively.
    56. 

  56. </p>
    57. 

  57. 

  58. <p>
    59. 

  59. C++ does not enjoy direct support for Design by Contract techniques: these
    60. 

  60. are customarily implemented as assertion code, often turned off in
    61. 

  61. release mode for performance reasons. Following this approach,
    62. 

  62. Boost.MultiIndex provides two distinct debugging modes:
    63. 

  63. <ul>
    64. 

  64.   <li><i>Safe mode</i> checks preconditions on the invocations to the
    65. 

  65.     facilities of the library,</li>
    66. 

  66.   <li><i>invariant-checking mode</i> performs post-execution checks aimed
    67. 

  67.     at ensuring that the internal consistency of the library is preserved.</li>
    68. 

  68. </ul>
    69. 

  69. These two modes are independent of each other and can be set on or off
    70. 

  70. individually. It is important to note that errors detected by safe mode are
    71. 

  71. due in principle to faulty code in the user's program, while
    72. 

  72. invariant-checking mode detects potential <i>internal</i> bugs in the
    73. 

  73. implementation of Boost.MultiIndex.
    74. 

  74. </p>
    75. 

  75. 

  76. <h2><a name="safe_mode">Safe mode</a></h2>
    77. 

  77. 

  78. <p>
    79. 

  79. The idea of adding precondition checking facilities to STL as a debugging aid
    80. 

  80. was first introduced by Cay S. Horstmann in his
    81. 

  81. <a href="http://www.horstmann.com/safestl.html">Safe STL</a> library and later
    82. 

  82. adopted by <a href="http://www.stlport.com/doc/debug_mode.html">STLport Debug
    83. 

  83. Mode</a>. Similarly, Boost.MultiIndex features the so-called <i>safe mode</i>
    84. 

  84. in which all sorts of preconditions are checked when dealing with iterators
    85. 

  85. and functions of the library.
    86. 

  86. </p>
    87. 

  87. 

  88. <p>
    89. 

  89. Boost.MultiIndex safe mode is set by globally defining the macro
    90. 

  90. <code>BOOST_MULTI_INDEX_ENABLE_SAFE_MODE</code>. Error conditions
    91. 

  91. are checked via the macro <code>BOOST_MULTI_INDEX_SAFE_MODE_ASSERT</code>, which
    92. 

  92. by default resolves to a call to <a href="../../../../libs/assert">
    93. 

  93. <code>BOOST_ASSERT</code></a>.
    94. 

  94. </p>
    95. 

  95. 

  96. <p>
    97. 

  97. If the user decides to define her own version of
    98. 

  98. <code>BOOST_MULTI_INDEX_SAFE_MODE_ASSERT</code>, it has to take the form
    99. 

  99. </p>
    100. 

  100. 

  101. <blockquote><pre>
    102. 

  102. <span class=identifier>BOOST_MULTI_INDEX_SAFE_MODE_ASSERT</span><span class=special>(</span><span class=identifier>expr</span><span class=special>,</span><span class=identifier>error_code</span><span class=special>)</span>
    103. 

  103. </pre></blockquote>
    104. 

  104. 

  105. <p>
    106. 

  106. where <code>expr</code> is the condition checked and <code>error_code</code>
    107. 

  107. is one value of the <code>safe_mode::error_code</code> enumeration:
    108. 

  108. </p>
    109. 

  109. 

  110. <blockquote><pre>
    111. 

  111. <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
    112. 

  112. 

  113. <span class=keyword>namespace</span> <span class=identifier>multi_index</span><span class=special>{</span>
    114. 

  114. 

  115. <span class=keyword>namespace</span> <span class=identifier>safe_mode</span><span class=special>{</span>
    116. 

  116. 

  117. <span class=keyword>enum</span> <span class=identifier>error_code</span>
    118. 

  118. <span class=special>{</span>
    119. 

  119.   <span class=identifier>invalid_iterator</span><span class=special>,</span>             <span class=comment>// vg. default cted or pointing to erased element</span>
    120. 

  120.   <span class=identifier>not_dereferenceable_iterator</span><span class=special>,</span> <span class=comment>// iterator is not dereferenceable</span>
    121. 

  121.   <span class=identifier>not_incrementable_iterator</span><span class=special>,</span>   <span class=comment>// iterator points to end of sequence</span>
    122. 

  122.   <span class=identifier>not_decrementable_iterator</span><span class=special>,</span>   <span class=comment>// iterator points to beginning of sequence</span> 
    123. 

  123.   <span class=identifier>not_owner</span><span class=special>,</span>                    <span class=comment>// iterator does not belong to the container</span>
    124. 

  124.   <span class=identifier>not_same_owner</span><span class=special>,</span>               <span class=comment>// iterators belong to different containers</span>
    125. 

  125.   <span class=identifier>invalid_range</span><span class=special>,</span>                <span class=comment>// last not reachable from first</span>
    126. 

  126.   <span class=identifier>inside_range</span><span class=special>,</span>                 <span class=comment>// iterator lies within a range (and it mustn't)</span>
    127. 

  127.   <span class=identifier>out_of_bounds</span><span class=special>,</span>                <span class=comment>// move attempted beyond container limits</span>
    128. 

  128.   <span class=identifier>same_container</span>                <span class=comment>// containers ought to be different</span>
    129. 

  129. <span class=special>};</span>
    130. 

  130. 

  131. <span class=special>}</span> <span class=comment>// namespace multi_index::safe_mode</span>
    132. 

  132. 

  133. <span class=special>}</span> <span class=comment>// namespace multi_index</span>
    134. 

  134. 

  135. <span class=special>}</span> <span class=comment>// namespace boost</span>
    136. 

  136. </pre></blockquote>
    137. 

  137. 

  138. <p>
    139. 

  139. For instance, the following replacement of
    140. 

  140. <code>BOOST_MULTI_INDEX_SAFE_MODE_ASSERT</code> throws an exception instead of
    141. 

  141. asserting:
    142. 

  142. </p>
    143. 

  143. 

  144. <blockquote><pre>
    145. 

  145. <span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>multi_index_container</span><span class=special>/</span><span class=identifier>safe_mode_errors</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
    146. 

  146. 

  147. <span class=keyword>struct</span> <span class=identifier>safe_mode_exception</span>
    148. 

  148. <span class=special>{</span>
    149. 

  149.   <span class=identifier>safe_mode_exception</span><span class=special>(</span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>multi_index</span><span class=special>::</span><span class=identifier>safe_mode</span><span class=special>::</span><span class=identifier>error_code</span> <span class=identifier>error_code</span><span class=special>):</span>
    150. 

  150.     <span class=identifier>error_code</span><span class=special>(</span><span class=identifier>error_code</span><span class=special>)</span>
    151. 

  151.   <span class=special>{}</span>
    152. 

  152. 

  153.   <span class=identifier>boost</span><span class=special>::</span><span class=identifier>multi_index</span><span class=special>::</span><span class=identifier>safe_mode</span><span class=special>::</span><span class=identifier>error_code</span> <span class=identifier>error_code</span><span class=special>;</span>
    154. 

  154. <span class=special>};</span>
    155. 

  155. 

  156. <span class=preprocessor>#define</span> <span class=identifier>BOOST_MULTI_INDEX_SAFE_MODE_ASSERT</span><span class=special>(</span><span class=identifier>expr</span><span class=special>,</span><span class=identifier>error_code</span><span class=special>)</span> <span class=special>\</span>
    157. 

  157. <span class=keyword>if</span><span class=special>(!(</span><span class=identifier>expr</span><span class=special>)){</span><span class=keyword>throw</span> <span class=identifier>safe_mode_exception</span><span class=special>(</span><span class=identifier>error_code</span><span class=special>);}</span>
    158. 

  158. 

  159. <span class=comment>// This has to go before the inclusion of any header from Boost.MultiIndex,
    160. 

  160. // except possibly safe_error_codes.hpp.</span>
    161. 

  161. </pre></blockquote>
    162. 

  162. 

  163. <p>
    164. 

  164. Other possibilites, like outputting to a log or firing some kind of alert, are
    165. 

  165. also implementable.
    166. 

  166. </p>
    167. 

  167. 

  168. <p>
    169. 

  169. <b>Warning:</b> Safe mode adds a very important overhead to the program
    170. 

  170. both in terms of space and time used, so in general it should not be set for
    171. 

  171. <code>NDEBUG</code> builds. Also, this mode is intended solely as a debugging aid,
    172. 

  172. and programs must not rely on it as part of their normal execution flow: in
    173. 

  173. particular, no guarantee is made that all possible precondition errors are diagnosed,
    174. 

  174. or that the checks remain stable across different versions of the library.
    175. 

  175. </p>
    176. 

  176. 

  177. <h3><a name="serialization_and_safe_mode">Serialization and safe mode</a></h3>
    178. 

  178. 

  179. <p>
    180. 

  180. Iterators restored from an archive are not subject to safe mode checks. This is
    181. 

  181. so because it is not possible to automatically know the associated
    182. 

  182. <code>multi_index_container</code> of an iterator from the serialization
    183. 

  183. information alone. However, if desired, a restored iterator can be converted to a
    184. 

  184. checked value by using the following workaround:
    185. 

  185. </p>
    186. 

  186. 

  187. <blockquote><pre>
    188. 

  188. <span class=identifier>employee_set</span> <span class=identifier>es</span><span class=special>;</span>
    189. 

  189. <span class=identifier>employee_set</span><span class=special>::</span><span class=identifier>nth_index</span><span class=special>&lt;</span><span class=number>1</span><span class=special>&gt;::</span><span class=identifier>iterator</span> <span class=identifier>it</span><span class=special>;</span>
    190. 

  190. 

  191. <span class=comment>// restore es and it from an archive ar</span>
    192. 

  192. <span class=identifier>ar</span><span class=special>&gt;&gt;</span><span class=identifier>es</span><span class=special>;</span>
    193. 

  193. <span class=identifier>ar</span><span class=special>&gt;&gt;</span><span class=identifier>it</span><span class=special>;</span> <span class=comment>// it won't benefit from safe mode checks
    194. 

  194. 

  195. // Turn it into a checked value by providing Boost.MultiIndex
    196. 

  196. // with info about the associated container.
    197. 

  197. // This statement has virtually zero cost if safe mode is turned off.</span>
    198. 

  198. <span class=identifier>it</span><span class=special>=</span><span class=identifier>es</span><span class=special>.</span><span class=identifier>project</span><span class=special>&lt;</span><span class=number>1</span><span class=special>&gt;(</span><span class=identifier>it</span><span class=special>);</span>
    199. 

  199. </pre></blockquote>
    200. 

  200. 

  201. <h2><a name="invariant_check">Invariant-checking mode</a></h2>
    202. 

  202. 

  203. <p>
    204. 

  204. The so called <i>invariant-checking mode</i> of Boost.MultiIndex can be
    205. 

  205. set by globally defining the macro
    206. 

  206. <code>BOOST_MULTI_INDEX_ENABLE_INVARIANT_CHECKING</code>.
    207. 

  207. When this mode is in effect, all public functions of Boost.MultiIndex
    208. 

  208. will perform post-execution tests aimed at ensuring that the basic
    209. 

  209. internal invariants of the data structures managed are preserved.
    210. 

  210. </p>
    211. 

  211. 

  212. <p>
    213. 

  213. If an invariant test fails, Boost.MultiIndex will indicate the failure
    214. 

  214. by means of the unary macro <code>BOOST_MULTI_INDEX_INVARIANT_ASSERT</code>.
    215. 

  215. Unless the user provides a definition for this macro, it defaults to
    216. 

  216. <a href="../../../../libs/assert">
    217. 

  217. <code>BOOST_ASSERT</code></a>. Any assertion of this kind should
    218. 

  218. be regarded in principle as a bug in the library. Please report such
    219. 

  219. problems, along with as much contextual information as possible, to the
    220. 

  220. maintainer of the library.
    221. 

  221. </p>
    222. 

  222. 

  223. <p>
    224. 

  224. It is recommended that users of Boost.MultiIndex always set the
    225. 

  225. invariant-checking mode in debug builds.
    226. 

  226. </p>
    227. 

  227. 

  228. <hr>
    229. 

  229. 

  230. <div class="prev_link"><a href="creation.html"><img src="../prev.gif" alt="container creation" border="0"><br>
    231. 

  231. Container creation
    232. 

  232. </a></div>
    233. 

  233. <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.MultiIndex tutorial" border="0"><br>
    234. 

  234. Boost.MultiIndex tutorial
    235. 

  235. </a></div>
    236. 

  236. <div class="next_link"><a href="techniques.html"><img src="../next.gif" alt="techniques" border="0"><br>
    237. 

  237. Techniques
    238. 

  238. </a></div><br clear="all" style="clear: all;">
    239. 

  239. 

  240. <br>
    241. 

  241. 

  242. <p>Revised July 07th 2017</p>
    243. 

  243. 

  244. <p>&copy; Copyright 2003-2017 Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
    245. 

  245. Distributed under the Boost Software 
    246. 

  246. License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt">
    247. 

  247. LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
    248. 

  248. http://www.boost.org/LICENSE_1_0.txt</a>)
    249. 

  249. </p>
    250. 

  250. 

  251. </body>
    252. 

  252. </html>
    253.