doc/html/intrusive/usage.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>How to use Boost.Intrusive</title>
   5 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   8 <link rel="up" href="../intrusive.html" title="Chapter&#160;15.&#160;Boost.Intrusive">
   9 <link rel="prev" href="intrusive_vs_nontrusive.html" title="Intrusive and non-intrusive containers">
  10 <link rel="next" href="usage_when.html" title="When to use?">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
  15 <td align="center"><a href="../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="intrusive_vs_nontrusive.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../intrusive.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="usage_when.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="intrusive.usage"></a><a class="link" href="usage.html" title="How to use Boost.Intrusive">How to use Boost.Intrusive</a>
  28 </h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="usage.html#intrusive.usage.usage_base_hook">Using base hooks</a></span></dt>
  31 <dt><span class="section"><a href="usage.html#intrusive.usage.usage_member_hook">Using member hooks</a></span></dt>
  32 <dt><span class="section"><a href="usage.html#intrusive.usage.usage_both_hooks">Using both hooks</a></span></dt>
  33 <dt><span class="section"><a href="usage.html#intrusive.usage.usage_lifetime">Object lifetime</a></span></dt>
  34 </dl></div>
  35 <p>
  36       If you plan to insert a class in an intrusive container, you have to make some
  37       decisions influencing the class definition itself. Each class that will be
  38       used in an intrusive container needs some appropriate data members storing
  39       the information needed by the container. We will take a simple intrusive container,
  40       the intrusive list (<code class="computeroutput"><a class="link" href="../boost/intrusive/list.html" title="Class template list">boost::intrusive::list</a></code>),
  41       for the following examples, but all <span class="bold"><strong>Boost.Intrusive</strong></span>
  42       containers are very similar. To compile the example using <code class="computeroutput"><a class="link" href="../boost/intrusive/list.html" title="Class template list">boost::intrusive::list</a></code>,
  43       just include:
  44     </p>
  45 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">intrusive</span><span class="special">/</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  46 </pre>
  47 <p>
  48       Every class to be inserted in an intrusive container, needs to contain a hook
  49       that will offer the necessary data and resources to be insertable in the container.
  50       With <span class="bold"><strong>Boost.Intrusive</strong></span> you just choose the hook
  51       to be a public base class or a public member of the class to be inserted.
  52       <span class="bold"><strong>Boost.Intrusive</strong></span> also offers more flexible
  53       hooks for advanced users, as explained in the chapter <a class="link" href="function_hooks.html" title="Using function hooks">Using
  54       function hooks</a>, but usually base or member hooks are good enough for
  55       most users.
  56     </p>
  57 <div class="section">
  58 <div class="titlepage"><div><div><h3 class="title">
  59 <a name="intrusive.usage.usage_base_hook"></a><a class="link" href="usage.html#intrusive.usage.usage_base_hook" title="Using base hooks">Using base hooks</a>
  60 </h3></div></div></div>
  61 <p>
  62         For <code class="computeroutput"><a class="link" href="../boost/intrusive/list.html" title="Class template list">list</a></code>, you can publicly
  63         derive from <code class="computeroutput"><a class="link" href="../boost/intrusive/list_base_hook.html" title="Class template list_base_hook">list_base_hook</a></code>.
  64       </p>
  65 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="special">...</span><span class="identifier">Options</span><span class="special">&gt;</span>
  66 <span class="keyword">class</span> <span class="identifier">list_base_hook</span><span class="special">;</span>
  67 </pre>
  68 <p>
  69         The class can take several options. <span class="bold"><strong>Boost.Intrusive</strong></span>
  70         classes receive arguments in the form <code class="computeroutput"><span class="identifier">option_name</span><span class="special">&lt;</span><span class="identifier">option_value</span><span class="special">&gt;</span></code>. You can specify the following options:
  71       </p>
  72 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  73 <li class="listitem">
  74             <span class="bold"><strong><code class="computeroutput"><span class="identifier">tag</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Tag</span><span class="special">&gt;</span></code></strong></span>:
  75             this argument serves as a tag, so you can derive from more than one
  76             <code class="computeroutput"><a class="link" href="../boost/intrusive/list_base_hook.html" title="Class template list_base_hook">list_base_hook</a></code>
  77             and hence put an object in multiple intrusive lists at the same time.
  78             An incomplete type can serve as a tag. If you specify two base hooks,
  79             you <span class="bold"><strong>must</strong></span> specify a different tag for
  80             each one. Example: <code class="computeroutput"><span class="identifier">list_base_hook</span><span class="special">&lt;</span> <span class="identifier">tag</span><span class="special">&lt;</span><span class="identifier">tag1</span><span class="special">&gt;</span> <span class="special">&gt;</span></code>.
  81             If no tag is specified a default one will be used (more on default tags
  82             later).
  83           </li>
  84 <li class="listitem">
  85             <span class="bold"><strong><code class="computeroutput"><span class="identifier">link_mode</span><span class="special">&lt;</span><span class="identifier">link_mode_type</span>
  86             <span class="identifier">LinkMode</span><span class="special">&gt;</span></code></strong></span>:
  87             The second template argument controls the linking policy. <span class="bold"><strong>Boost.Intrusive</strong></span>
  88             currently supports 3 modes: <code class="computeroutput"><span class="identifier">normal_link</span></code>,
  89             <code class="computeroutput"><span class="identifier">safe_link</span></code> and <code class="computeroutput"><span class="identifier">auto_unlink</span></code>. By default, <code class="computeroutput"><span class="identifier">safe_link</span></code> mode is used. More about
  90             these in sections <a class="link" href="safe_hook.html" title="Safe hooks">Safe hooks</a>
  91             and <a class="link" href="auto_unlink_hooks.html" title="Auto-unlink hooks">Auto-unlink hooks</a>.
  92             Example: <code class="computeroutput"><span class="identifier">list_base_hook</span><span class="special">&lt;</span> <span class="identifier">link_mode</span><span class="special">&lt;</span><span class="identifier">auto_unlink</span><span class="special">&gt;</span> <span class="special">&gt;</span></code>
  93           </li>
  94 <li class="listitem">
  95             <span class="bold"><strong><code class="computeroutput"><span class="identifier">void_pointer</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">VoidPointer</span><span class="special">&gt;</span></code></strong></span>:
  96             this option is the pointer type to be used internally in the hook. The
  97             default value is <code class="computeroutput"><span class="keyword">void</span> <span class="special">*</span></code>,
  98             which means that raw pointers will be used in the hook. More about this
  99             in the section titled <a class="link" href="using_smart_pointers.html" title="Using smart pointers with Boost.Intrusive containers">Using
 100             smart pointers with Boost.Intrusive containers</a>. Example: <code class="computeroutput"><span class="identifier">list_base_hook</span><span class="special">&lt;</span>
 101             <span class="identifier">void_pointer</span><span class="special">&lt;</span>
 102             <span class="identifier">my_smart_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span></code>
 103           </li>
 104 </ul></div>
 105 <p>
 106         For the following examples, let's forget the options and use the default
 107         values:
 108       </p>
 109 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">intrusive</span><span class="special">/</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 110
 111 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">intrusive</span><span class="special">;</span>
 112
 113 <span class="keyword">class</span> <span class="identifier">Foo</span>
 114    <span class="comment">//Base hook with default tag, raw pointers and safe_link mode</span>
 115    <span class="special">:</span>  <span class="keyword">public</span> <span class="identifier">list_base_hook</span><span class="special">&lt;&gt;</span>
 116 <span class="special">{</span> <span class="comment">/**/</span> <span class="special">};</span>
 117 </pre>
 118 <p>
 119         After that, we can define the intrusive list:
 120       </p>
 121 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="special">...</span><span class="identifier">Options</span><span class="special">&gt;</span>
 122 <span class="keyword">class</span> <span class="identifier">list</span><span class="special">;</span>
 123 </pre>
 124 <p>
 125         <code class="computeroutput"><span class="identifier">list</span></code> receives the type to
 126         be inserted in the container (<code class="computeroutput"><span class="identifier">T</span></code>)
 127         as the first parameter and optionally, the user can specify options. We have
 128         3 option types:
 129       </p>
 130 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 131 <li class="listitem">
 132             <span class="bold"><strong><code class="computeroutput"><span class="identifier">base_hook</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Hook</span><span class="special">&gt;</span></code></strong></span>
 133             / <span class="bold"><strong><code class="computeroutput"><span class="identifier">member_hook</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Hook</span><span class="special">,</span> <span class="identifier">Hook</span> <span class="identifier">T</span><span class="special">::*</span> <span class="identifier">PtrToMember</span><span class="special">&gt;</span></code></strong></span>
 134             / <span class="bold"><strong><code class="computeroutput"><span class="identifier">value_traits</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ValueTraits</span><span class="special">&gt;</span></code></strong></span>:
 135             All these options specify the relationship between the type <code class="computeroutput"><span class="identifier">T</span></code> to be inserted in the list and the
 136             hook (since we can have several hooks in the same <code class="computeroutput"><span class="identifier">T</span></code>
 137             type). <code class="computeroutput"><span class="identifier">member_hook</span></code> will
 138             be explained a bit later and <code class="computeroutput"><span class="identifier">value_traits</span></code>
 139             will be explained in the <a class="link" href="value_traits.html" title="Containers with custom ValueTraits">Containers
 140             with custom ValueTraits</a> section. <span class="bold"><strong>If no option
 141             is specified, the container will be configured to use the base hook with
 142             the default tag</strong></span>. Some options configured for the hook (the
 143             type of the pointers, link mode, etc.) will be propagated to the container.
 144           </li>
 145 <li class="listitem">
 146             <span class="bold"><strong><code class="computeroutput"><span class="identifier">constant_time_size</span><span class="special">&lt;</span><span class="keyword">bool</span> <span class="identifier">Enabled</span><span class="special">&gt;</span></code></strong></span>:
 147             Specifies if a constant time <code class="computeroutput"><span class="identifier">size</span><span class="special">()</span></code> function is demanded for the container.
 148             This will instruct the intrusive container to store an additional member
 149             to keep track of the current size of the container. By default, constant-time
 150             size is activated.
 151           </li>
 152 <li class="listitem">
 153             <span class="bold"><strong><code class="computeroutput"><span class="identifier">size_type</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">SizeType</span><span class="special">&gt;</span></code></strong></span>:
 154             Specifies an unsigned type that can hold the size of the container. This
 155             type will be the type returned by <code class="computeroutput"><span class="identifier">list</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span></code> and the type stored in the intrusive
 156             container if <code class="computeroutput"><span class="identifier">constant_time_size</span><span class="special">&lt;</span><span class="keyword">true</span><span class="special">&gt;</span></code> is requested. The user normally will
 157             not need to change this type, but some containers can have a <code class="computeroutput"><span class="identifier">size_type</span></code> that might be different from
 158             <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code> (for example, STL-like containers
 159             use the <code class="computeroutput"><span class="identifier">size_type</span></code> defined
 160             by their allocator). <span class="bold"><strong>Boost.Intrusive</strong></span>
 161             can be used to implement such containers specifying the the type of the
 162             size. By default the type is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>.
 163           </li>
 164 </ul></div>
 165 <p>
 166         Example of a constant-time size intrusive list that will store Foo objects,
 167         using the base hook with the default tag:
 168       </p>
 169 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">&gt;</span> <span class="identifier">FooList</span><span class="special">;</span>
 170 </pre>
 171 <p>
 172         Example of an intrusive list with non constant-time size that will store
 173         Foo objects:
 174       </p>
 175 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">,</span> <span class="identifier">constant_time_size</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">FooList</span><span class="special">;</span>
 176 </pre>
 177 <p>
 178         Remember that the user must specify the base hook in the container declaration
 179         if the base hook has no default tag, because that usually means that the
 180         type has more than one base hook, and a container shall know which hook will
 181         be using:
 182       </p>
 183 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">intrusive</span><span class="special">/</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 184
 185 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">intrusive</span><span class="special">;</span>
 186
 187 <span class="keyword">struct</span> <span class="identifier">my_tag1</span><span class="special">;</span>
 188 <span class="keyword">struct</span> <span class="identifier">my_tag2</span><span class="special">;</span>
 189
 190 <span class="keyword">typedef</span> <span class="identifier">list_base_hook</span><span class="special">&lt;</span> <span class="identifier">tag</span><span class="special">&lt;</span><span class="identifier">my_tag</span><span class="special">&gt;</span>  <span class="special">&gt;</span> <span class="identifier">BaseHook</span><span class="special">;</span>
 191 <span class="keyword">typedef</span> <span class="identifier">list_base_hook</span><span class="special">&lt;</span> <span class="identifier">tag</span><span class="special">&lt;</span><span class="identifier">my_tag2</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">BaseHook2</span><span class="special">;</span>
 192 <span class="keyword">class</span> <span class="identifier">Foo</span>   <span class="special">:</span>  <span class="keyword">public</span> <span class="identifier">BaseHook</span><span class="special">,</span> <span class="keyword">public</span> <span class="identifier">BaseHook2</span>
 193 <span class="special">{</span> <span class="comment">/**/</span> <span class="special">};</span>
 194
 195 <span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span> <span class="identifier">Foo</span><span class="special">,</span> <span class="identifier">base_hook</span><span class="special">&lt;</span><span class="identifier">BaseHook</span><span class="special">&gt;</span>  <span class="special">&gt;</span> <span class="identifier">FooList</span><span class="special">;</span>
 196 <span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span> <span class="identifier">Foo</span><span class="special">,</span> <span class="identifier">base_hook</span><span class="special">&lt;</span><span class="identifier">BaseHook2</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">FooList2</span><span class="special">;</span>
 197 </pre>
 198 <p>
 199         Once the list is defined, we can use it:
 200       </p>
 201 <pre class="programlisting"><span class="comment">//An object to be inserted in the list</span>
 202 <span class="identifier">Foo</span> <span class="identifier">foo_object</span><span class="special">;</span>
 203 <span class="identifier">FooList</span> <span class="identifier">list</span><span class="special">;</span>
 204
 205 <span class="identifier">list</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">object</span><span class="special">);</span>
 206
 207 <span class="identifier">assert</span><span class="special">(&amp;</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">front</span><span class="special">()</span> <span class="special">==</span> <span class="special">&amp;</span><span class="identifier">foo_object</span><span class="special">);</span>
 208 </pre>
 209 </div>
 210 <div class="section">
 211 <div class="titlepage"><div><div><h3 class="title">
 212 <a name="intrusive.usage.usage_member_hook"></a><a class="link" href="usage.html#intrusive.usage.usage_member_hook" title="Using member hooks">Using member hooks</a>
 213 </h3></div></div></div>
 214 <p>
 215         Sometimes an 'is-a' relationship between list hooks and the list value types
 216         is not desirable. In this case, using a member hook as a data member instead
 217         of 'disturbing' the hierarchy might be the right way: you can add a public
 218         data member <code class="computeroutput"><span class="identifier">list_member_hook</span><span class="special">&lt;...&gt;</span></code> to your class. This class can
 219         be configured with the same options as <code class="computeroutput"><span class="identifier">list_base_hook</span></code>
 220         except the option <code class="computeroutput"><span class="identifier">tag</span></code>:
 221       </p>
 222 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="special">...</span><span class="identifier">Options</span><span class="special">&gt;</span>
 223 <span class="keyword">class</span> <span class="identifier">list_member_hook</span><span class="special">;</span>
 224 </pre>
 225 <p>
 226         Example:
 227       </p>
 228 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">intrusive</span><span class="special">/</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 229
 230 <span class="keyword">class</span> <span class="identifier">Foo</span>
 231 <span class="special">{</span>
 232    <span class="keyword">public</span><span class="special">:</span>
 233    <span class="identifier">list_member_hook</span><span class="special">&lt;&gt;</span> <span class="identifier">hook_</span><span class="special">;</span>
 234    <span class="comment">//...</span>
 235 <span class="special">};</span>
 236 </pre>
 237 <p>
 238         When member hooks are used, the <code class="computeroutput"><span class="identifier">member_hook</span></code>
 239         option is used to configure the list:
 240       </p>
 241 <pre class="programlisting"><span class="comment">//This option will configure "list" to use the member hook</span>
 242 <span class="keyword">typedef</span> <span class="identifier">member_hook</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">,</span> <span class="identifier">list_member_hook</span><span class="special">&lt;&gt;,</span> <span class="special">&amp;</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">hook_</span><span class="special">&gt;</span> <span class="identifier">MemberHookOption</span><span class="special">;</span>
 243
 244 <span class="comment">//This list will use the member hook</span>
 245 <span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">,</span> <span class="identifier">MemberHookOption</span><span class="special">&gt;</span> <span class="identifier">FooList</span><span class="special">;</span>
 246 </pre>
 247 <p>
 248         Now we can use the container:
 249       </p>
 250 <pre class="programlisting"><span class="comment">//An object to be inserted in the list</span>
 251 <span class="identifier">Foo</span> <span class="identifier">foo_object</span><span class="special">;</span>
 252 <span class="identifier">FooList</span> <span class="identifier">list</span><span class="special">;</span>
 253
 254 <span class="identifier">list</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">object</span><span class="special">);</span>
 255
 256 <span class="identifier">assert</span><span class="special">(&amp;</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">front</span><span class="special">()</span> <span class="special">==</span> <span class="special">&amp;</span><span class="identifier">foo_object</span><span class="special">);</span>
 257 </pre>
 258 </div>
 259 <p>
 260       However, member hooks have some implementation limitations: If there is a virtual
 261       inheritance relationship between the parent and the member hook, then the distance
 262       between the parent and the hook is not a compile-time fixed value so obtaining
 263       the address of the parent from the member hook is not possible without reverse
 264       engineering compiler produced RTTI. Apart from this, the non-standard pointer
 265       to member implementation for classes with complex inheritance relationships
 266       in MSVC ABI compatible-compilers is not supported by member hooks since it
 267       also depends on compiler-produced RTTI information.
 268     </p>
 269 <div class="section">
 270 <div class="titlepage"><div><div><h3 class="title">
 271 <a name="intrusive.usage.usage_both_hooks"></a><a class="link" href="usage.html#intrusive.usage.usage_both_hooks" title="Using both hooks">Using both hooks</a>
 272 </h3></div></div></div>
 273 <p>
 274         You can insert the same object in several intrusive containers at the same
 275         time, using one hook per container. This is a full example using base and
 276         member hooks:
 277       </p>
 278 <p>
 279 </p>
 280 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">intrusive</span><span class="special">/</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 281 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
 282
 283 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">intrusive</span><span class="special">;</span>
 284
 285 <span class="keyword">class</span> <span class="identifier">MyClass</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">list_base_hook</span><span class="special">&lt;&gt;</span>
 286 <span class="special">{</span>
 287    <span class="keyword">int</span> <span class="identifier">int_</span><span class="special">;</span>
 288
 289    <span class="keyword">public</span><span class="special">:</span>
 290    <span class="identifier">list_member_hook</span><span class="special">&lt;&gt;</span> <span class="identifier">member_hook_</span><span class="special">;</span>
 291
 292    <span class="identifier">MyClass</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">:</span>  <span class="identifier">int_</span><span class="special">(</span><span class="identifier">i</span><span class="special">)</span>  <span class="special">{}</span>
 293 <span class="special">};</span>
 294
 295 <span class="comment">//Define a list that will store MyClass using the base hook</span>
 296 <span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">MyClass</span><span class="special">&gt;</span> <span class="identifier">BaseList</span><span class="special">;</span>
 297
 298 <span class="comment">//Define a list that will store MyClass using the member hook</span>
 299 <span class="keyword">typedef</span> <span class="identifier">member_hook</span>
 300    <span class="special">&lt;</span> <span class="identifier">MyClass</span><span class="special">,</span> <span class="identifier">list_member_hook</span><span class="special">&lt;&gt;,</span> <span class="special">&amp;</span><span class="identifier">MyClass</span><span class="special">::</span><span class="identifier">member_hook_</span><span class="special">&gt;</span> <span class="identifier">MemberOption</span><span class="special">;</span>
 301 <span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">MyClass</span><span class="special">,</span> <span class="identifier">MemberOption</span><span class="special">&gt;</span> <span class="identifier">MemberList</span><span class="special">;</span>
 302
 303 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 304 <span class="special">{</span>
 305    <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">MyClass</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">VectIt</span><span class="special">;</span>
 306
 307    <span class="comment">//Create several MyClass objects, each one with a different value</span>
 308    <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">MyClass</span><span class="special">&gt;</span> <span class="identifier">values</span><span class="special">;</span>
 309    <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>  <span class="identifier">values</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">MyClass</span><span class="special">(</span><span class="identifier">i</span><span class="special">));</span>
 310
 311    <span class="identifier">BaseList</span> <span class="identifier">baselist</span><span class="special">;</span>
 312    <span class="identifier">MemberList</span> <span class="identifier">memberlist</span><span class="special">;</span>
 313
 314    <span class="comment">//Now insert them in the reverse order in the base hook list</span>
 315    <span class="keyword">for</span><span class="special">(</span><span class="identifier">VectIt</span> <span class="identifier">it</span><span class="special">(</span><span class="identifier">values</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()),</span> <span class="identifier">itend</span><span class="special">(</span><span class="identifier">values</span><span class="special">.</span><span class="identifier">end</span><span class="special">())</span>
 316       <span class="special">;</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">itend</span>  <span class="special">;</span> <span class="special">++</span><span class="identifier">it</span><span class="special">){</span>
 317       <span class="identifier">baselist</span><span class="special">.</span><span class="identifier">push_front</span><span class="special">(*</span><span class="identifier">it</span><span class="special">);</span>
 318    <span class="special">}</span>
 319
 320    <span class="comment">//Now insert them in the same order as in vector in the member hook list</span>
 321    <span class="keyword">for</span><span class="special">(</span><span class="identifier">VectIt</span> <span class="identifier">it</span><span class="special">(</span><span class="identifier">values</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()),</span> <span class="identifier">itend</span><span class="special">(</span><span class="identifier">values</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">itend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</span>
 322       <span class="identifier">memberlist</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(*</span><span class="identifier">it</span><span class="special">);</span>
 323
 324    <span class="comment">//Now test lists</span>
 325    <span class="special">{</span>
 326       <span class="identifier">BaseList</span><span class="special">::</span><span class="identifier">reverse_iterator</span> <span class="identifier">rbit</span><span class="special">(</span><span class="identifier">baselist</span><span class="special">.</span><span class="identifier">rbegin</span><span class="special">());</span>
 327       <span class="identifier">MemberList</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">mit</span><span class="special">(</span><span class="identifier">memberlist</span><span class="special">.</span><span class="identifier">begin</span><span class="special">());</span>
 328       <span class="identifier">VectIt</span>  <span class="identifier">it</span><span class="special">(</span><span class="identifier">values</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()),</span> <span class="identifier">itend</span><span class="special">(</span><span class="identifier">values</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span>
 329
 330       <span class="comment">//Test the objects inserted in the base hook list</span>
 331       <span class="keyword">for</span><span class="special">(;</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">itend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">it</span><span class="special">,</span> <span class="special">++</span><span class="identifier">rbit</span><span class="special">)</span>
 332          <span class="keyword">if</span><span class="special">(&amp;*</span><span class="identifier">rbit</span> <span class="special">!=</span> <span class="special">&amp;*</span><span class="identifier">it</span><span class="special">)</span>   <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span>
 333
 334       <span class="comment">//Test the objects inserted in the member hook list</span>
 335       <span class="keyword">for</span><span class="special">(</span><span class="identifier">it</span> <span class="special">=</span> <span class="identifier">values</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">itend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">it</span><span class="special">,</span> <span class="special">++</span><span class="identifier">mit</span><span class="special">)</span>
 336          <span class="keyword">if</span><span class="special">(&amp;*</span><span class="identifier">mit</span> <span class="special">!=</span> <span class="special">&amp;*</span><span class="identifier">it</span><span class="special">)</span>    <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span>
 337    <span class="special">}</span>
 338
 339    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 340 <span class="special">}</span>
 341 </pre>
 342 <p>
 343       </p>
 344 </div>
 345 <div class="section">
 346 <div class="titlepage"><div><div><h3 class="title">
 347 <a name="intrusive.usage.usage_lifetime"></a><a class="link" href="usage.html#intrusive.usage.usage_lifetime" title="Object lifetime">Object lifetime</a>
 348 </h3></div></div></div>
 349 <p>
 350         Even if the interface of <code class="computeroutput"><a class="link" href="../boost/intrusive/list.html" title="Class template list">list</a></code>
 351         is similar to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span></code>, its usage is a bit different: You
 352         always have to keep in mind that you directly store objects in intrusive
 353         containers, not copies. The lifetime of a stored object is not bound to or
 354         managed by the container:
 355       </p>
 356 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 357 <li class="listitem">
 358             When the container gets destroyed before the object, the object is not
 359             destroyed, so you have to be careful to avoid resource leaks.
 360           </li>
 361 <li class="listitem">
 362             When the object is destroyed before the container, your program is likely
 363             to crash, because the container contains a pointer to an non-existing
 364             object.
 365           </li>
 366 </ul></div>
 367 </div>
 368 </div>
 369 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 370 <td align="left"></td>
 371 <td align="right"><div class="copyright-footer">Copyright &#169; 2005 Olaf Krzikalla<br>Copyright &#169; 2006-2013 Ion Gaztanaga<p>
 372         Distributed under the Boost Software License, Version 1.0. (See accompanying
 373         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>)
 374       </p>
 375 </div></td>
 376 </tr></table>
 377 <hr>
 378 <div class="spirit-nav">
 379 <a accesskey="p" href="intrusive_vs_nontrusive.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../intrusive.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="usage_when.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 380 </div>
 381 </body>
 382 </html>