ceph/src/boost/libs/optional/doc/html/boost_optional/in_place_factories.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>In-Place Factories</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="Chapter&#160;1.&#160;Boost.Optional">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
   9 <link rel="prev" href="detailed_semantics.html" title="Detailed Semantics">
  10 <link rel="next" href="a_note_about_optional_bool_.html" title="A note about optional&lt;bool&gt;">
  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="detailed_semantics.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="a_note_about_optional_bool_.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="boost_optional.in_place_factories"></a><a class="link" href="in_place_factories.html" title="In-Place Factories">In-Place Factories</a>
  28 </h2></div></div></div>
  29 <p>
  30       One of the typical problems with wrappers and containers is that their interfaces
  31       usually provide an operation to initialize or assign the contained object as
  32       a copy of some other object. This not only requires the underlying type to
  33       be <a href="../../../../utility/CopyConstructible.html" target="_top">Copy Constructible</a>,
  34       but also requires the existence of a fully constructed object, often temporary,
  35       just to follow the copy from:
  36     </p>
  37 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span>
  38 <span class="special">{</span>
  39     <span class="identifier">X</span> <span class="special">(</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">)</span> <span class="special">;</span>
  40 <span class="special">}</span> <span class="special">;</span>
  41
  42 <span class="keyword">class</span> <span class="identifier">W</span>
  43 <span class="special">{</span>
  44     <span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
  45
  46     <span class="keyword">public</span><span class="special">:</span>
  47
  48     <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
  49 <span class="special">}</span> <span class="special">;</span>
  50
  51 <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
  52 <span class="special">{</span>
  53     <span class="comment">// Temporary object created.</span>
  54     <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
  55 <span class="special">}</span>
  56 </pre>
  57 <p>
  58       A solution to this problem is to support direct construction of the contained
  59       object right in the container's storage. In this scheme, the user only needs
  60       to supply the arguments to the constructor to use in the wrapped object construction.
  61     </p>
  62 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">W</span>
  63 <span class="special">{</span>
  64     <span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
  65
  66     <span class="keyword">public</span><span class="special">:</span>
  67
  68     <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
  69     <span class="identifier">W</span> <span class="special">(</span> <span class="keyword">int</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">a1</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">a0</span><span class="special">,</span><span class="identifier">a1</span><span class="special">)</span> <span class="special">{}</span>
  70 <span class="special">}</span> <span class="special">;</span>
  71
  72 <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
  73 <span class="special">{</span>
  74     <span class="comment">// Wrapped object constructed in-place</span>
  75     <span class="comment">// No temporary created.</span>
  76     <span class="identifier">W</span> <span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">)</span> <span class="special">;</span>
  77 <span class="special">}</span>
  78 </pre>
  79 <p>
  80       A limitation of this method is that it doesn't scale well to wrapped objects
  81       with multiple constructors nor to generic code were the constructor overloads
  82       are unknown.
  83     </p>
  84 <p>
  85       The solution presented in this library is the family of <span class="bold"><strong>InPlaceFactories</strong></span>
  86       and <span class="bold"><strong>TypedInPlaceFactories</strong></span>. These factories
  87       are a family of classes which encapsulate an increasing number of arbitrary
  88       constructor parameters and supply a method to construct an object of a given
  89       type using those parameters at an address specified by the user via placement
  90       new.
  91     </p>
  92 <p>
  93       For example, one member of this family looks like:
  94     </p>
  95 <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="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">&gt;</span>
  96 <span class="keyword">class</span> <span class="identifier">TypedInPlaceFactory2</span>
  97 <span class="special">{</span>
  98     <span class="identifier">A0</span> <span class="identifier">m_a0</span> <span class="special">;</span> <span class="identifier">A1</span> <span class="identifier">m_a1</span> <span class="special">;</span>
  99
 100     <span class="keyword">public</span><span class="special">:</span>
 101
 102     <span class="identifier">TypedInPlaceFactory2</span><span class="special">(</span> <span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a1</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">m_a0</span><span class="special">(</span><span class="identifier">a0</span><span class="special">),</span> <span class="identifier">m_a1</span><span class="special">(</span><span class="identifier">a1</span><span class="special">)</span> <span class="special">{}</span>
 103
 104     <span class="keyword">void</span> <span class="identifier">construct</span> <span class="special">(</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">p</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">new</span> <span class="special">(</span><span class="identifier">p</span><span class="special">)</span> <span class="identifier">T</span><span class="special">(</span><span class="identifier">m_a0</span><span class="special">,</span><span class="identifier">m_a1</span><span class="special">)</span> <span class="special">;</span> <span class="special">}</span>
 105  <span class="special">}</span> <span class="special">;</span>
 106 </pre>
 107 <p>
 108       A wrapper class aware of this can use it as:
 109     </p>
 110 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">W</span>
 111 <span class="special">{</span>
 112     <span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
 113
 114     <span class="keyword">public</span><span class="special">:</span>
 115
 116     <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
 117     <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory2</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">fac</span> <span class="special">)</span> <span class="special">{</span> <span class="identifier">fac</span><span class="special">.</span><span class="identifier">construct</span><span class="special">(&amp;</span><span class="identifier">wrapped_</span><span class="special">)</span> <span class="special">;</span> <span class="special">}</span>
 118 <span class="special">}</span> <span class="special">;</span>
 119
 120 <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
 121 <span class="special">{</span>
 122     <span class="comment">// Wrapped object constructed in-place via a TypedInPlaceFactory.</span>
 123     <span class="comment">// No temporary created.</span>
 124     <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory2</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">))</span> <span class="special">;</span>
 125 <span class="special">}</span>
 126 </pre>
 127 <p>
 128       The factories are divided in two groups:
 129     </p>
 130 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 131 <li class="listitem">
 132           <span class="underline">TypedInPlaceFactories</span>: those which
 133           take the target type as a primary template parameter.
 134         </li>
 135 <li class="listitem">
 136           <span class="underline">InPlaceFactories</span>: those with a template
 137           <code class="computeroutput"><span class="identifier">construct</span><span class="special">(</span><span class="keyword">void</span><span class="special">*)</span></code> member
 138           function taking the target type.
 139         </li>
 140 </ul></div>
 141 <p>
 142       Within each group, all the family members differ only in the number of parameters
 143       allowed.
 144     </p>
 145 <p>
 146       This library provides an overloaded set of helper template functions to construct
 147       these factories without requiring unnecessary template parameters:
 148     </p>
 149 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,...,</span><span class="keyword">class</span> <span class="identifier">AN</span><span class="special">&gt;</span>
 150 <span class="identifier">InPlaceFactoryN</span> <span class="special">&lt;</span><span class="identifier">A0</span><span class="special">,...,</span><span class="identifier">AN</span><span class="special">&gt;</span> <span class="identifier">in_place</span> <span class="special">(</span> <span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a0</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">AN</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">aN</span><span class="special">)</span> <span class="special">;</span>
 151
 152 <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="identifier">A0</span><span class="special">,...,</span><span class="keyword">class</span> <span class="identifier">AN</span><span class="special">&gt;</span>
 153 <span class="identifier">TypedInPlaceFactoryN</span> <span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">A0</span><span class="special">,...,</span><span class="identifier">AN</span><span class="special">&gt;</span> <span class="identifier">in_place</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a0</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">AN</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">aN</span><span class="special">)</span> <span class="special">;</span>
 154 </pre>
 155 <p>
 156       In-place factories can be used generically by the wrapper and user as follows:
 157     </p>
 158 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">W</span>
 159 <span class="special">{</span>
 160     <span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
 161
 162     <span class="keyword">public</span><span class="special">:</span>
 163
 164     <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
 165
 166     <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">InPlaceFactory</span> <span class="special">&gt;</span>
 167     <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">InPlaceFactory</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">fac</span> <span class="special">)</span> <span class="special">{</span> <span class="identifier">fac</span><span class="special">.</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;</span><span class="identifier">construct</span><span class="special">(&amp;</span><span class="identifier">wrapped_</span><span class="special">)</span> <span class="special">;</span> <span class="special">}</span>
 168
 169 <span class="special">}</span> <span class="special">;</span>
 170
 171 <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
 172 <span class="special">{</span>
 173     <span class="comment">// Wrapped object constructed in-place via a InPlaceFactory.</span>
 174     <span class="comment">// No temporary created.</span>
 175     <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">in_place</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
 176 <span class="special">}</span>
 177 </pre>
 178 <p>
 179       The factories are implemented in the headers: <a href="../../../../../boost/utility/in_place_factory.hpp" target="_top">in_place_factory.hpp</a>
 180       and <a href="../../../../../boost/utility/typed_in_place_factory.hpp" target="_top">typed_in_place_factory.hpp</a>
 181     </p>
 182 </div>
 183 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 184 <td align="left"></td>
 185 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
 186         Distributed under the Boost Software License, Version 1.0. (See accompanying
 187         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>)
 188       </p>
 189 </div></td>
 190 </tr></table>
 191 <hr>
 192 <div class="spirit-nav">
 193 <a accesskey="p" href="detailed_semantics.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="a_note_about_optional_bool_.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 194 </div>
 195 </body>
 196 </html>