doc/html/intrusive/usage.html

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