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