libs/flyweight/doc/reference/flyweight.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0.1 Transitional//EN">
   2
   3 <html>
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   6 <title>Boost.Flyweight Documentation - flyweight reference</title>
   7 <link rel="stylesheet" href="../style.css" type="text/css">
   8 <link rel="start" href="../index.html">
   9 <link rel="prev" href="index.html">
  10 <link rel="up" href="index.html">
  11 <link rel="next" href="key_value.html">
  12 </head>
  13
  14 <body>
  15 <h1><img src="../../../../boost.png" alt="Boost logo" align=
  16 "middle" width="277" height="86">Boost.Flyweight
  17 <code>flyweight</code> reference</h1>
  18
  19 <div class="prev_link"><a href="index.html"><img src="../prev.gif" alt="Boost.Flyweight reference" border="0"><br>
  20 Boost.Flyweight reference
  21 </a></div>
  22 <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"><br>
  23 Boost.Flyweight reference
  24 </a></div>
  25 <div class="next_link"><a href="key_value.html"><img src="../next.gif" alt="key-value flyweights" border="0"><br>
  26 Key-value flyweights
  27 </a></div><br clear="all" style="clear: all;">
  28
  29 <hr>
  30
  31 <h2>Contents</h2>
  32
  33 <ul>
  34   <li><a href="#flyweight_fwd_synopsis">Header
  35     <code>"boost/flyweight/flyweight_fwd.hpp"</code> synopsis</a></li>
  36   <li><a href="#synopsis">Header
  37     <code>"boost/flyweight/flyweight.hpp"</code> synopsis</a>
  38     <ul>
  39       <li><a href="#flyweight">Class template <code>flyweight</code></a>
  40         <ul>
  41           <li><a href="#instantiation_types">Instantiation types</a></li>
  42           <li><a href="#static_init">Static data initialization</a></li>
  43           <li><a href="#constructors">Constructors, copy and assignment</a></li>
  44           <li><a href="#convertibility">Convertibility to the underlying types</a></li>
  45           <li><a href="#modifiers">Modifiers</a></li>
  46           <li><a href="#comparison">Comparison operators</a></li>
  47           <li><a href="#specialized">Specialized algorithms</a></li>
  48           <li><a href="#config_macros">Configuration macros</a></li>
  49         </ul>
  50       </li>
  51     </ul>
  52   </li>
  53   <li><a href="#serialize_synopsis">Header
  54     <code>"boost/flyweight/serialize.hpp"</code> synopsis</a>
  55     <ul>
  56       <li><a href="#serialization">Serialization</a></li>
  57     </ul>
  58   </li>
  59 </ul>
  60
  61 <h2>
  62 <a name="flyweight_fwd_synopsis">Header
  63 <a href="../../../../boost/flyweight/flyweight_fwd.hpp"><code>"boost/flyweight/flyweight_fwd.hpp"</code></a>
  64 synopsis</a>
  65 </h2>
  66
  67 <blockquote><pre>
  68 <span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>iosfwd</span><span class=special>&gt;</span>
  69
  70 <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
  71
  72 <span class=keyword>namespace</span> <span class=identifier>flyweights</span><span class=special>{</span>
  73
  74 <span class=keyword>template</span><span class=special>&lt;</span>
  75   <span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span>
  76   <span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>=</span><b>implementation defined</b><span class=special>,</span>
  77   <span class=keyword>typename</span> <span class=identifier>Arg2</span><span class=special>=</span><b>implementation defined</b><span class=special>,</span>
  78   <span class=keyword>typename</span> <span class=identifier>Arg3</span><span class=special>=</span><b>implementation defined</b><span class=special>,</span>
  79   <span class=keyword>typename</span> <span class=identifier>Arg4</span><span class=special>=</span><b>implementation defined</b><span class=special>,</span>
  80   <span class=keyword>typename</span> <span class=identifier>Arg5</span><span class=special>=</span><b>implementation defined</b>
  81 <span class=special>&gt;</span>
  82 <span class=keyword>class</span> <span class=identifier>flyweight</span><span class=special>;</span>
  83
  84 <span class=comment>// comparison:
  85
  86 // <b>OP</b> is any of ==,&lt;,!=,&gt;,&gt;=,&lt;=</span>
  87
  88 <span class=keyword>template</span><span class=special>&lt;</span>
  89   <span class=keyword>typename</span> <span class=identifier>T1</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg11</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg15</span><span class=special>,</span>
  90   <span class=keyword>typename</span> <span class=identifier>T2</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg21</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg25</span>
  91 <span class=special>&gt;</span>
  92 <span class=keyword>bool</span> <span class=keyword>operator</span> <span class=identifier><b><i>OP</i></b></span><span class=special>(</span>
  93   <span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&lt;</span><span class=identifier>T1</span><span class=special>,</span><span class=identifier>Arg11</span><span class=special>,...,</span><span class=identifier>Arg15</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span><span class=special>,</span>
  94   <span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&lt;</span><span class=identifier>T2</span><span class=special>,</span><span class=identifier>Arg21</span><span class=special>,...,</span><span class=identifier>Arg25</span><span class=special>&gt;&amp;</span> <span class=identifier>y</span><span class=special>);</span>
  95
  96 <span class=keyword>template</span><span class=special>&lt;</span>
  97   <span class=keyword>typename</span> <span class=identifier>T1</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg11</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg15</span><span class=special>,</span>
  98   <span class=keyword>typename</span> <span class=identifier>T2</span>
  99 <span class=special>&gt;</span>
 100 <span class=keyword>bool</span> <span class=keyword>operator</span> <span class=identifier><b><i>OP</i></b></span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&lt;</span><span class=identifier>T1</span><span class=special>,</span><span class=identifier>Arg11</span><span class=special>,...,</span><span class=identifier>Arg15</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>T2</span><span class=special>&amp;</span> <span class=identifier>y</span><span class=special>);</span>
 101
 102 <span class=keyword>template</span><span class=special>&lt;</span>
 103   <span class=keyword>typename</span> <span class=identifier>T1</span><span class=special>,</span>
 104   <span class=keyword>typename</span> <span class=identifier>T2</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg21</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg25</span>
 105 <span class=special>&gt;</span>
 106 <span class=keyword>bool</span> <span class=keyword>operator</span> <span class=identifier><b><i>OP</i></b></span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>T1</span><span class=special>&amp;</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&lt;</span><span class=identifier>T2</span><span class=special>,</span><span class=identifier>Arg21</span><span class=special>,...,</span><span class=identifier>Arg25</span><span class=special>&gt;&amp;</span> <span class=identifier>y</span><span class=special>);</span>
 107
 108 <span class=comment>// specialized algorithms:</span>
 109
 110 <span class=keyword>template</span><span class=special>&lt;</span><span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span><span class=special>&gt;</span>
 111 <span class=keyword>inline</span> <span class=keyword>void</span> <span class=identifier>swap</span><span class=special>(</span>
 112   <span class=identifier>flyweight</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span><span class=special>,</span><span class=identifier>flyweight</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>&gt;&amp;</span> <span class=identifier>y</span><span class=special>);</span>
 113
 114 <span class=keyword>template</span><span class=special>&lt;</span>
 115   <span class=keyword>typename</span> <span class=identifier>ElemType</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Traits</span><span class=special>,</span>
 116   <span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span>
 117 <span class=special>&gt;</span>
 118 <span class=keyword>inline</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_ostream</span><span class=special>&lt;</span><span class=identifier>ElemType</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>&gt;&amp;</span> <span class=keyword>operator</span><span class=special>&lt;&lt;(</span>
 119   <span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_ostream</span><span class=special>&lt;</span><span class=identifier>ElemType</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>&gt;&amp;</span> <span class=identifier>out</span><span class=special>,</span>
 120   <span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 121
 122 <span class=keyword>template</span><span class=special>&lt;</span>
 123   <span class=keyword>typename</span> <span class=identifier>ElemType</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Traits</span><span class=special>,</span>
 124   <span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span>
 125 <span class=special>&gt;</span>
 126 <span class=keyword>inline</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_ostream</span><span class=special>&lt;</span><span class=identifier>ElemType</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>&gt;&amp;</span> <span class=keyword>operator</span><span class=special>&gt;&gt;(</span>
 127   <span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_istream</span><span class=special>&lt;</span><span class=identifier>ElemType</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>&gt;&amp;</span> <span class=identifier>in</span><span class=special>,</span>
 128   <span class=identifier>flyweight</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 129
 130 <span class=special>}</span> <span class=comment>// namespace boost::flyweights</span>
 131
 132 <span class=keyword>using</span> <span class=identifier>flyweights</span><span class=special>::</span><span class=identifier>flyweight</span><span class=special>;</span>
 133
 134 <span class=special>}</span> <span class=comment>// namespace boost</span>
 135 </pre></blockquote>
 136
 137 <p>
 138 <code>flyweight_fwd.hpp</code> forward declares the class template
 139 <a href="#flyweight"><code>flyweight</code></a> and its associated global functions.
 140 </p>
 141
 142 <h2>
 143 <a name="synopsis">Header
 144 <a href="../../../../boost/flyweight/flyweight.hpp"><code>"boost/flyweight/flyweight.hpp"</code></a>
 145 synopsis</a>
 146 </h2>
 147
 148 <h3><a name="flyweight">
 149 Class template <code>flyweight</code>
 150 </a></h3>
 151
 152 <p>
 153 Objects of type <code>flyweight&lt;...&gt;</code> provide access to immutable
 154 values of type <code>flyweight&lt;...&gt;::value_type</code>, with the following advantages over using
 155 plain <code>value_type</code> objects:
 156 <ul>
 157   <li>Flyweight objects with equivalent value share the same representation
 158     (the associated <code>value_type</code> object).
 159   </li>
 160   <li>The size of flyweights is typically that of a pointer, which is in general
 161     smaller than <code>sizeof(value_type)</code>.
 162   </li>
 163 </ul>
 164
 165 So, if the level of redundancy (ratio of total objects to different values)
 166 is high enough, substituting a suitable instantiation of <code>flyweight</code>
 167 for <code>value_type</code> results in a reduction in memory usage.
 168 </p>
 169
 170 <p>
 171 <code>flyweight</code> is parameterized according to some aspects:
 172 <ul>
 173   <li>Types <code>key_value</code> and <code>value_type</code>
 174     (possibly equal), where <code>key_type</code> serves as a
 175     key type to lookup and construct internal shared instances of
 176     objects of <code>value_type</code>.
 177   </li>
 178   <li>An optional <a href="tags.html#tag">tag</a> type meant to syntactically
 179      differentiate between otherwise identical instantiations.
 180   </li>
 181   <li>The <a href="factories.html#factory">factory class</a> used to store
 182     and retrieve the shared value objects.
 183   </li>
 184   <li>The type of <a href="holders.html#holder">holder</a> used to
 185     instantiate the flyweight factory and a mutex object, both of
 186     which are unique to each specialization of the <code>flyweight</code>
 187     class template.
 188   </li>
 189   <li>A <a href="locking.html#locking">locking policy</a> determining
 190     the synchronization mechanisms for internal access to shared resources.
 191   </li>
 192   <li>A <a href="tracking.html#tracking">tracking policy</a> which controls
 193    how values are treated when all their associated flyweight objects are
 194    destroyed.
 195   </li>
 196 </ul>
 197 These aspects impact the internal structure and behavior
 198 of the <code>flyweight</code> instantiation in the following manner:
 199 <ul>
 200   <li>Each instantation of <code>flyweight</code> internally owns
 201     a unique factory object and a unique synchronization
 202     <a href="locking.html#preliminary">mutex</a> object, both of which
 203     are created through the use of an associated holder type.
 204   </li>
 205   <li>The flyweight factory stores elements of an undisclosed type
 206     <code>Entry</code> that is implicitly convertible to
 207     <code>const key_type&amp;</code> and also stores a subobject of
 208     <code>value_type</code>. Every flyweight object is associated
 209     to a <code>value_type</code> subobject of some <code>Entry</code>
 210     stored in the factory.
 211   </li>
 212   <li>The associated mutex object is used to protect all invocations
 213     to the insertion and deletion functions of the internal flyweight
 214     factory.
 215   </li>
 216   <li>Each flyweight object internally stores a value of some
 217     undisclosed type <code>Handle</code>. <code>Handle</code> and
 218     the <code>Entry</code> type referred to above are obtained
 219     from invocations to the associated tracking policy, in the
 220     manner described for this concept.
 221   </li>
 222 </ul>
 223 In what follows, we implicitly assume that <code>key_type</code> equivalence
 224 refers to the equivalence relationship induced by the factory class used.
 225 Also, two values of <code>value_type</code> are considered equivalent
 226 if they are constructed from equivalent keys, or are copies of
 227 objects constructed from equivalent keys.
 228 </p>
 229
 230 <blockquote><pre>
 231 <span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>initializer_list</span><span class=special>&gt;</span>
 232
 233 <span class=keyword>template</span><span class=special>&lt;</span>
 234   <span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span>
 235   <span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg2</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg3</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg4</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span>
 236 <span class=special>&gt;</span>
 237 <span class=keyword>class</span> <span class=identifier>flyweight</span>
 238 <span class=special>{</span>
 239 <span class=keyword>public</span><span class=special>:</span>
 240   <span class=keyword>typedef</span> <span class=identifier><b>dependent on T</b></span> <span class=identifier>key_type</span><span class=special>;</span>
 241   <span class=keyword>typedef</span> <span class=identifier><b>dependent on T</b></span> <span class=identifier>value_type</span><span class=special>;</span>
 242
 243   <span class=comment>// static data initialization:</span>
 244
 245   <span class=keyword>static</span> <span class=keyword>bool</span> <span class=identifier>init</span><span class=special>();</span>
 246   <span class=keyword>class</span> <span class=identifier>initializer</span><span class=special>{</span><span class=keyword>public</span><span class=special>:</span><span class=identifier>initializer</span><span class=special>();</span><span class=special>};</span>
 247
 248   <span class=comment>// construct/copy/destroy:</span>
 249
 250   <span class=identifier>flyweight</span><span class=special>();</span>
 251
 252   <span class=keyword>template</span><span class=special>&lt;</span><span class=keyword>typename</span><span class=special>...</span> <span class=identifier>Args</span><span class=special>&gt;</span>
 253   <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>Args</span><span class=special>&amp;&amp;...</span> <span class=identifier>args</span><span class=special>);</span>
 254
 255   <span class=keyword>template</span><span class=special>&lt;</span><span class=keyword>typename</span> <span class=identifier>V</span><span class=special>&gt;</span>
 256   <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>initializer_list</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>&gt;</span> <span class=identifier>list</span><span class=special>);</span>
 257
 258   <span class=identifier>flyweight</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 259   <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>flyweight</span><span class=special>&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 260   <span class=identifier>flyweight</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&amp;&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 261   <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>flyweight</span><span class=special>&amp;&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 262
 263   <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 264   <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>value_type</span><span class=special>&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 265   <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&amp;&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 266   <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>value_type</span><span class=special>&amp;&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 267
 268   <span class=keyword>template</span><span class=special>&lt;</span><span class=keyword>typename</span> <span class=identifier>V</span><span class=special>&gt;</span>
 269   <span class=identifier>flyweight</span><span class=special>&amp;</span> <span class=keyword>operator</span><span class=special>=(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>initializer_list</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>&gt;</span> <span class=identifier>list</span><span class=special>);</span>
 270
 271   <span class=identifier>flyweight</span><span class=special>&amp;</span> <span class=keyword>operator</span><span class=special>=(</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 272
 273   <span class=identifier>flyweight</span><span class=special>&amp;</span> <span class=keyword>operator</span><span class=special>=(</span><span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 274   <span class=identifier>flyweight</span><span class=special>&amp;</span> <span class=keyword>operator</span><span class=special>=(</span><span class=identifier>value_type</span><span class=special>&amp;&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 275
 276   <span class=comment>// convertibility to underlying type:</span>
 277
 278   <span class=keyword>const</span> <span class=identifier>key_type</span><span class=special>&amp;</span>   <span class=identifier>get_key</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
 279   <span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&amp;</span> <span class=identifier>get</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
 280   <span class=keyword>operator</span> <span class=keyword>const</span>    <span class=identifier>value_type</span><span class=special>&amp;()</span><span class=keyword>const</span><span class=special>;</span>
 281
 282   <span class=comment>// modifiers:</span>
 283
 284   <span class=keyword>void</span> <span class=identifier>swap</span><span class=special>(</span><span class=identifier>flyweight</span><span class=special>&amp;</span> <span class=identifier>x</span><span class=special>);</span>
 285 <span class=special>};</span>
 286 </pre></blockquote>
 287
 288 <h4><a name="instantiation_types">Instantiation types</a></h4>
 289
 290 <p>
 291 <code>T</code> can be either:
 292 <ul>
 293   <li>An arbitrary type,</li>
 294   <li>a type of the form
 295     <a href="key_value.html#key_value_construct"><code>key_value&lt;Key,Value[,KeyFromValue]&gt;</code></a>.</li>
 296 </ul>
 297 In the first case, the nested types <code>key_type</code> and <code>value_type</code>
 298 are both equal to <code>T</code>. In the second case, <code>key_type</code>=<code>Key</code>,
 299 <code>value_type</code>=<code>Value</code>; we say then that the instantiation
 300 of <code>flyweight</code> is a <i>key-value</i> flyweight.
 301 <code>value_type</code> is the type of the values flyweight objects give access to,
 302 while value lookup is based on associated <code>key_type</code> values.
 303 <code>key_value</code> must be
 304 <a href="http://www.sgi.com/tech/stl/Assignable.html"><code>Assignable</code></a>
 305 and <code>value_type</code> must be constructible from <code>key_type</code>;
 306 additionally, <code>key_value</code> must
 307 conform to any extra requirements imposed by the type of factory used.
 308 For key-value flyweights, it is guaranteed that the creation or assignment of a flyweight
 309 object results in at most one construction (or copy construction in some
 310 particular cases) of an object
 311 of <code>value_type</code>, and this construction only occurs in the case that no
 312 equivalent value existed previously in the flyweight factory.
 313 </p>
 314
 315 <p>
 316 The types <code>Arg1</code>, ... , <code>Arg5</code>, if provided, must be any
 317 of the following, in no particular order:
 318 <ul>
 319   <li>A <a href="tags.html#tag">tag</a>,</li>
 320   <li>a <a href="factories.html#factory">factory specifier</a>,</li>
 321   <li>a <a href="holders.html#holder">holder specifier</a>,</li>
 322   <li>a <a href="locking.html#locking">locking policy</a>,</li>
 323   <li>a <a href="tracking.html#tracking">tracking policy</a>.</li>
 324 </ul>
 325 No aspect can be specified twice. Each internal component of the
 326 <code>flyweight</code> instantiation is obtained through use of the
 327 corresponding specifier; for instance, the factory results from a
 328 certain (MPL) invocation of the given factory specifier, the internal
 329 mutex from the given locking policy, etc.
 330 The default configuration arguments are:
 331 <ul>
 332   <li>No tagging,</li>
 333   <li><a href="factories.html#hashed_factory"><code>hashed_factory&lt;&gt;</code></a>,</li>
 334   <li><a href="holders.html#static_holder"><code>static_holder</code></a>,</li>
 335   <li><a href="locking.html#simple_locking"><code>simple_locking</code></a>,</li>
 336   <li><a href="tracking.html#refcounted"><code>refcounted</code></a> tracking policy.</li>
 337 </ul>
 338 </p>
 339
 340 <h4><a name="static_init">Static data initialization</a></h4>
 341
 342 <p>
 343 The static data internal to a given <code>flyweight</code> instantiation
 344 (factory instance, etc.) is constructed during the dynamic initialization
 345 phase of the program and always before the first program-wide use of the
 346 instantiated class. The following utilities can be
 347 used when more control about the moment of construction is required.
 348 </p>
 349
 350 <code>static bool init();</code>
 351
 352 <blockquote>
 353 <b>Effects:</b> After execution of this function the static data associated
 354 to the instantiation of <code>flyweight</code> is guaranteed to be
 355 constructed.<br>
 356 <b>Note:</b> Concurrent execution of this function is not thread safe.
 357 </blockquote>
 358
 359 <code>initializer::initializer();</code>
 360
 361 <blockquote>
 362 <b>Effects:</b> Executes <code>init()</code>.
 363 </blockquote>
 364
 365 <h4><a name="constructors">Constructors, copy and assignment</a></h4>
 366
 367 <code>flyweight();</code>
 368
 369 <blockquote>
 370 <b>Effects:</b> Constructs a <code>flyweight</code> object with the value
 371 <code>value_type(key_type())</code>
 372 if <code>flyweight</code> is key-value
 373 or <code>value_type()</code>
 374 otherwise.
 375 </blockquote>
 376
 377 <a name="fwd_ctor">
 378 <code>template&lt;typename... Args&gt;<br>
 379 explicit flyweight(Args&amp;&amp;... args);</code></a>
 380
 381 <blockquote>
 382 <b>Effects:</b> Constructs a <code>flyweight</code> object with the value
 383 <code>value_type(key_type(std::forward&lt;Args&gt;(args)...))</code>
 384 if <code>flyweight</code> is key-value
 385 or <code>value_type(std::forward&lt;Args&gt;(args)...)</code>
 386 otherwise.<br>
 387 <b>Note:</b> In compilers without variadic template support, the implementation
 388 replaces this constructor with a number of overloads accepting
 389 any combination of const/non-const lvalue/rvalue reference arguments
 390 up to a maximum number that
 391 can be globally <a href="#limit_num_ctor_args">configured</a> by the user.
 392 </blockquote>
 393
 394 <code>template&lt;typename V&gt;<br>
 395 flyweight(std::initializer_list&lt;V&gt; list);</code>
 396
 397 <blockquote>
 398 <b>Effects:</b> Constructs a <code>flyweight</code> object with the value
 399 <code>value_type(key_type(list))</code> if <code>flyweight</code> is key-value
 400 or <code>value_type(list)</code> otherwise.<br>
 401 <b>Note:</b> The specialization for a particular <code>std::initializer_list&lt;V'&gt;</code>
 402 of this member function template is not available unless
 403 <code>key_type</code> is constructible from
 404 <code>std::initializer_list&lt;V'&gt;</code>.
 405 </blockquote>
 406
 407 <code>flyweight(const flyweight&amp; x);<br>
 408 flyweight(flyweight&amp; x);<br>
 409 flyweight(const flyweight&amp;&amp; x);<br>
 410 flyweight(flyweight&amp;&amp; x);</code>
 411
 412 <blockquote>
 413 <b>Effects:</b> Constructs a <code>flyweight</code> object associated to
 414 the same value as <code>x</code>.<br>
 415 <b>Exception safety:</b> <code>nothrow</code>.
 416 </blockquote>
 417
 418 <code>explicit flyweight(const value_type&amp; x);<br>
 419 explicit flyweight(value_type&amp; x);<br>
 420 explicit flyweight(const value_type&amp;&amp; x);<br>
 421 explicit flyweight(value_type&amp;&amp; x);</code>
 422
 423 <blockquote>
 424 <b>Requires:</b> If <code>flyweight</code> is key-value,
 425 <code>value_type</code> is
 426 <a href="http://www.sgi.com/tech/stl/Assignable.html"><code>Assignable</code></a>
 427 and the
 428 <a href="key_value.html#key_extractor"><code>Key Extractor</code></a>
 429 <code>KeyFromValue</code> must have been supplied as part of the
 430 <code>key_value&lt;&gt;</code> construct.<br>
 431 <b>Effects:</b> Constructs a <code>flyweight</code> associated to a
 432 copy of <code>x</code> or with a <code>value_type</code> constructed
 433 from a key equivalent to that associated to <code>x</code>. For non-key-value
 434 flyweights, <code>x</code> is its own key; for key-value flyweights,
 435 the key is extracted through use of an object of type <code>KeyFromValue</code>.<br>
 436 </blockquote>
 437
 438 <code>template&lt;typename V&gt;<br>
 439 flyweight&amp; operator=(std::initializer_list&lt;V&gt; list);</code>
 440
 441 <blockquote>
 442 <b>Effects:</b> <code>*this=flyweight(list)</code>.<br>
 443 <b>Returns:</b> <code>*this</code>.<br>
 444 <b>Note:</b> The specialization for a particular <code>std::initializer_list&lt;V'&gt;</code>
 445 of this member function template is not available unless
 446 <code>key_type</code> is constructible from
 447 <code>std::initializer_list&lt;V'&gt;</code>.
 448 </blockquote>
 449
 450 <code>flyweight&amp; operator=(const flyweight&amp; x);</code>
 451
 452 <blockquote>
 453 <b>Effects:</b> Associates the <code>flyweight</code> object with the same value
 454 as <code>x</code>.<br>
 455 <b>Returns:</b> <code>*this</code>.<br>
 456 <b>Exception safety:</b> <code>nothrow</code>.
 457 </blockquote>
 458
 459 <code>flyweight&amp; operator=(const value_type&amp; x);<br>
 460 flyweight&amp; operator=(value_type&amp;&amp; x);</code>
 461
 462 <blockquote>
 463 <b>Effects:</b> <code>*this=flyweight(x)</code> (first overload),
 464 <code>*this=flyweight(std::move(x))</code> (second overload).<br>
 465 <b>Returns:</b> <code>*this</code>.<br>
 466 </blockquote>
 467
 468 <h4><a name="convertibility">Convertibility to the underlying types</a></h4>
 469
 470 <code>const key_type&amp; get_key()const;</code>
 471
 472 <blockquote>
 473 <b>Return:</b> A copy of the key used to construct the
 474 <code>value_type</code> associated to the <code>flyweight</code>
 475 object.<br>
 476 <b>Exception safety:</b> If <code>flyweight</code> is not key-value or
 477 if <code>KeyFromValue</code> was not provided, <code>nothrow</code>.
 478 </blockquote>
 479
 480 <code>const value_type&amp; get()const;<br>
 481         operator const value_type&amp;()const;</code>
 482
 483 <blockquote>
 484 <b>Return:</b> The value associated to the <code>flyweight</code>
 485 object.<br>
 486 <b>Exception safety:</b> <code>nothrow</code>.
 487 </blockquote>
 488
 489 <h4><a name="modifiers">Modifiers</a></h4>
 490
 491 <code>void swap(flyweight&amp; x);</code>
 492
 493 <blockquote>
 494 <b>Effects:</b> Swaps the associations to <code>value_type</code>s each
 495 flyweight object has. No swapping of <code>key_type</code> or
 496 <code>value_type</code> objects is done.<br>
 497 <b>Exception safety:</b> <code>nothrow</code>.
 498 </blockquote>
 499
 500 <h4><a name="comparison">Comparison operators</a></h4>
 501
 502 <code>template&lt;<br>
 503 &nbsp;&nbsp;typename T1,typename Arg11,...,typename Arg15,<br>
 504 &nbsp;&nbsp;typename T2,typename Arg21,...,typename Arg25<br>
 505 &gt;<br>
 506 bool operator ==(<br>
 507 &nbsp;&nbsp;const flyweight&lt;T1,Arg11,...,Arg15&gt;&amp; x,<br>
 508 &nbsp;&nbsp;const flyweight&lt;T2,Arg21,...,Arg25&gt;&amp; y);</code>
 509
 510 <blockquote>
 511 <b>Returns:</b> If <code>x</code> and <code>y</code> are of the same type, returns
 512 <code>true</code> if and only if they are associated to the same value; if
 513 <code>x</code> and <code>y</code> have different types, returns
 514 <code>x.get()==y.get()</code>.<br>
 515 <b>Exception safety:</b> If <code>x</code> and <code>y</code> are of the same type,
 516 <code>nothrow</code>.
 517 </blockquote>
 518
 519 <code>template&lt;<br>
 520 &nbsp;&nbsp;typename T1,typename Arg11,...,typename Arg15,<br>
 521 &nbsp;&nbsp;typename T2<br>
 522 &gt;<br>
 523 bool operator ==(const flyweight&lt;T1,Arg11,...,Arg15&gt;&amp; x,const T2&amp; y);</code>
 524
 525 <blockquote>
 526 <b>Returns:</b> <code>x.get()==y</code>.
 527 </blockquote>
 528
 529 <code>template&lt;<br>
 530 &nbsp;&nbsp;typename T1,<br>
 531 &nbsp;&nbsp;typename T2,typename Arg21,...,typename Arg25<br>
 532 &gt;<br>
 533 bool operator ==(const T1&amp; x,const flyweight&lt;T2,Arg21,...,Arg25&gt;&amp; y);</code>
 534
 535 <blockquote>
 536 <b>Returns:</b> <code>x==y.get()</code>.
 537 </blockquote>
 538
 539 <code>template&lt;<br>
 540 &nbsp;&nbsp;typename T1,typename Arg11,...,typename Arg15,<br>
 541 &nbsp;&nbsp;typename T2,typename Arg21,...,typename Arg25<br>
 542 &gt;<br>
 543 bool operator &lt;(<br>
 544 &nbsp;&nbsp;const flyweight&lt;T1,Arg11,...,Arg15&gt;&amp; x,<br>
 545 &nbsp;&nbsp;const flyweight&lt;T2,Arg21,...,Arg25&gt;&amp; y);</code>
 546
 547 <blockquote>
 548 <b>Returns:</b> <code>x.get()&lt;y.get()</code>.
 549 </blockquote>
 550
 551 <code>template&lt;<br>
 552 &nbsp;&nbsp;typename T1,typename Arg11,...,typename Arg15,<br>
 553 &nbsp;&nbsp;typename T2<br>
 554 &gt;<br>
 555 bool operator &lt;(const flyweight&lt;T1,Arg11,...,Arg15&gt;&amp; x,const T2&amp; y);</code>
 556
 557 <blockquote>
 558 <b>Returns:</b> <code>x.get()&lt;y</code>.
 559 </blockquote>
 560
 561 <code>template&lt;<br>
 562 &nbsp;&nbsp;typename T1,<br>
 563 &nbsp;&nbsp;typename T2,typename Arg21,...,typename Arg25<br>
 564 &gt;<br>
 565 bool operator &lt;(const T1&amp; x,const flyweight&lt;T2,Arg21,...,Arg25&gt;&amp; y);</code>
 566
 567 <blockquote>
 568 <b>Returns:</b> <code>x&lt;y.get()</code>.
 569 </blockquote>
 570
 571
 572 <code>template&lt;<br>
 573 &nbsp;&nbsp;typename T1,typename Arg11,...,typename Arg15,<br>
 574 &nbsp;&nbsp;typename T2,typename Arg21,...,typename Arg25<br>
 575 &gt;<br>
 576 bool operator <b><i>OP</i></b>(<br>
 577 &nbsp;&nbsp;const flyweight&lt;T1,Arg11,...,Arg15&gt;&amp; x,<br>
 578 &nbsp;&nbsp;const flyweight&lt;T2,Arg21,...,Arg25&gt;&amp; y);<br>
 579 template&lt;<br>
 580 &nbsp;&nbsp;typename T1,typename Arg11,...,typename Arg15,<br>
 581 &nbsp;&nbsp;typename T2<br>
 582 &gt;<br>
 583 bool operator <b><i>OP</i></b>(const flyweight&lt;T1,Arg11,...,Arg15&gt;&amp; x,const T2&amp; y);</br>
 584 template&lt;<br>
 585 &nbsp;&nbsp;typename T1,<br>
 586 &nbsp;&nbsp;typename T2,typename Arg21,...,typename Arg25<br>
 587 &gt;<br>
 588 bool operator <b><i>OP</i></b>(const T1&amp; x,const flyweight&lt;T2,Arg21,...,Arg25&gt;&amp; y);</code>
 589
 590 <p>
 591 (<code><b><i>OP</i></b></code> is any of <code>!=</code>, <code>></code>,
 592 <code>>=</code>, <code>&lt;=</code>.)
 593 </p>
 594
 595 <blockquote>
 596 <b>Returns:</b> <code>true</code> if and only if
 597 <blockquote>
 598 <code>!(x==y)</code> (<code><b><i>OP</i></b></code> is <code>!=</code>),<br>
 599 <code>&nbsp;&nbsp;y&lt;&nbsp;x&nbsp;</code> (<code><b><i>OP</i></b></code> is <code>>&nbsp;</code>),<br>
 600 <code>!(x&lt;&nbsp;y)</code> (<code><b><i>OP</i></b></code> is <code>>=</code>),<br>
 601 <code>!(y&lt;&nbsp;x)</code> (<code><b><i>OP</i></b></code> is <code>&lt;=</code>).
 602 </blockquote>
 603 </blockquote>
 604
 605 <h4><a name="specialized">Specialized algorithms</a></h4>
 606
 607 <code>template&lt;typename T,typename Arg1,...,typename Arg5&gt;<br>
 608 inline void swap(<br>
 609 &nbsp;&nbsp;flyweight&lt;T,Arg1,...,Arg5&gt;&amp; x,flyweight&lt;T,Arg1,...,Arg5&gt;&amp; y);</code>
 610
 611 <blockquote>
 612 <b>Effects:</b> <code>x.swap(y)</code>.
 613 </blockquote>
 614
 615 <code>template&lt;<br>
 616 &nbsp;&nbsp;typename ElemType,typename Traits, <br>
 617 &nbsp;&nbsp;typename T,typename Arg1,...,typename Arg5<br>
 618 &gt;<br>
 619 inline std::basic_ostream&lt;ElemType,Traits&gt;&amp; operator&lt;&lt;(<br>
 620 &nbsp;&nbsp;std::basic_ostream&lt;ElemType,Traits&gt;&amp; out,<br>
 621 &nbsp;&nbsp;const flyweight&lt;T,Arg1,...,Arg5&gt;&amp; x);</code>
 622
 623 <blockquote>
 624 <b>Effects:</b> <code>out&lt;&lt;x.get()</code>.<br>
 625 <b>Returns:</b> <code>out</code>.
 626 </blockquote>
 627
 628 <code>template&lt;<br>
 629 &nbsp;&nbsp;typename ElemType,typename Traits, <br>
 630 &nbsp;&nbsp;typename T,typename Arg1,...,typename Arg5<br>
 631 &gt;<br>
 632 inline std::basic_ostream&lt;ElemType,Traits&gt;&amp; operator&gt;&gt;(<br>
 633 &nbsp;&nbsp;std::basic_istream&lt;ElemType,Traits&gt;&amp; in,<br>
 634 &nbsp;&nbsp;flyweight&lt;T,Arg1,...,Arg5&gt;&amp; x);</code>
 635
 636 <blockquote>
 637 <b>Requires:</b> If <code>flyweight</code> is key-value,
 638 <code>value_type</code> is
 639 <a href="http://www.sgi.com/tech/stl/Assignable.html"><code>Assignable</code></a>
 640 and the
 641 <a href="key_value.html#key_extractor"><code>Key Extractor</code></a>
 642 <code>KeyFromValue</code> must have been supplied as part of the
 643 <code>key_value&lt;&gt;</code> construct.<br>
 644 <b>Effects:</b> Reads an object of type <code>value_type</code> from <code>in</code>
 645 and assigns it to <code>x</code>.<br>
 646 <b>Returns:</b> <code>in</code>.
 647 </blockquote>
 648
 649 <h4><a name="config_macros">Configuration macros</a></h4>
 650
 651 <a name="limit_num_ctor_args">
 652 <code>BOOST_FLYWEIGHT_LIMIT_PERFECT_FWD_ARGS</code></a>
 653
 654 <blockquote>
 655 <b>Effects:</b> In compilers without variadic template support,
 656 globally define this macro to set the maximum number of
 657 arguments accepted by <code>flyweight</code>
 658 <a href="#fwd_ctor">forwarding constructor</a>, which by default
 659 is 5.
 660 </blockquote>
 661
 662 <h2>
 663 <a name="serialize_synopsis">Header
 664 </a><a href="../../../../boost/flyweight/serialize.hpp"><code>"boost/flyweight/serialize.hpp"</code></a>
 665 synopsis
 666 </h2>
 667
 668 <p>
 669 <code>serialize.hpp</code> includes the necessary functionality for interoperability
 670 of <code>flyweight</code> with
 671 <a href="../../../serialization/index.html">Boost.Serialization</a>.
 672 </p>
 673
 674 <h3><a name="serialization">Serialization</a></h3>
 675
 676 <p>
 677 <code>flyweight</code>s can be archived and retrieved by means of
 678 <a href="../../../serialization/index.html">Boost.Serialization</a>. Regular as well
 679 as XML archives are supported.
 680 Serialization is done in an efficient manner so that saving equivalent <code>flyweight</code>s
 681 result in their common <code>key_type</code> value being stored only once, regardless
 682 of whether <code>key_type</code> is
 683 <a href="../../../serialization/doc/traits.html#tracking">tracked</a> by
 684 Boost.Serialization or not.
 685 </p>
 686
 687 Operation: saving of a <code>flyweight</code> object <code>x</code> to an
 688 output archive (XML archive) <code>ar</code>.
 689
 690 <blockquote>
 691 <b>Requires:</b> <code>key_type</code> is serializable (XML-serializable).<br>
 692 <b>Effects:</b> The value <code>k=x.get_key()</code> is saved into <code>ar</code> as
 693 part of this operation or of a previous saving operation of a <code>flyweight</code>
 694 object with the same key.<br>
 695 <b>Exception safety:</b> Strong with respect to <code>x</code>. If an exception
 696 is thrown, <code>ar</code> may be left in an inconsistent state.
 697 </blockquote>
 698
 699 Operation: loading of a <code>flyweight</code> <code>x'</code> from an
 700 input archive (XML archive) <code>ar</code>.
 701
 702 <blockquote>
 703 <b>Requires:</b> <code>key_type</code> is serializable (XML-serializable).<br>
 704 <b>Effects:</b> <code>x'</code> is associated to a value constructed from a key
 705 equivalent to <code>k'</code>, a restored copy of the value <code>k</code>
 706 defined above.<br>
 707 <b>Exception safety:</b> Strong with respect to <code>x'</code>. If an exception
 708 is thrown, <code>ar</code> may be left in an inconsistent state.
 709 </blockquote>
 710
 711 <hr>
 712
 713 <div class="prev_link"><a href="index.html"><img src="../prev.gif" alt="Boost.Flyweight reference" border="0"><br>
 714 Boost.Flyweight reference
 715 </a></div>
 716 <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"><br>
 717 Boost.Flyweight reference
 718 </a></div>
 719 <div class="next_link"><a href="key_value.html"><img src="../next.gif" alt="key-value flyweights" border="0"><br>
 720 Key-value flyweights
 721 </a></div><br clear="all" style="clear: all;">
 722
 723 <br>
 724
 725 <p>Revised September 3rd 2014</p>
 726
 727 <p>&copy; Copyright 2006-2014 Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
 728 Distributed under the Boost Software
 729 License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt">
 730 LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
 731 http://www.boost.org/LICENSE_1_0.txt</a>)
 732 </p>
 733
 734 </body>
 735 </html>