ceph/src/boost/libs/flyweight/doc/tutorial/index.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 - Tutorial</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="basics.html">
  12 </head>
  13
  14 <body>
  15 <h1><img src="../../../../boost.png" alt="Boost logo" align=
  16 "middle" width="277" height="86">Boost.Flyweight Tutorial</h1>
  17
  18 <div class="prev_link"><a href="../index.html"><img src="../prev.gif" alt="index" border="0"><br>
  19 Index
  20 </a></div>
  21 <div class="up_link"><a href="../index.html"><img src="../up.gif" alt="index" border="0"><br>
  22 Index
  23 </a></div>
  24 <div class="next_link"><a href="basics.html"><img src="../next.gif" alt="basics" border="0"><br>
  25 Basics
  26 </a></div><br clear="all" style="clear: all;">
  27
  28 <hr>
  29
  30 <h2>Contents</h2>
  31
  32 <ul>
  33   <li><a href="#rationale">Rationale</a></li>
  34   <li><a href="#namespace">Namespace</a></li>
  35   <li><a href="#guide">Guide to the reader</a></li>
  36   <li><a href="basics.html">Basics</a></li>
  37   <li><a href="key_value.html">Key-value flyweights</a></li>
  38   <li><a href="configuration.html">Configuring Boost.Flyweight</a></li>
  39   <li><a href="extension.html">Extending Boost.Flyweight</a></li>
  40   <li><a href="technical.html">Technical issues</a></li>
  41   <li><a href="lambda_expressions.html">Annex: MPL Lambda expressions</a></li>
  42 </ul>
  43
  44 <h2><a name="rationale">Rationale</a></h2>
  45
  46 <span style="float:left;margin-right:20px;margin-bottom:20px">
  47 <p align="center">
  48 <img src="flyweight_rep.png"
  49 alt="representation of a flyweight scenario"
  50 width="424" height="320"><br>
  51 <b>Fig. 1: Representation of a flyweight scenario.</b>
  52 </p>
  53 </span>
  54
  55 <p>
  56 Consider an application that has to manage large quantities of objects of
  57 moderate size, potentially requiring more memory than reasonably available.
  58 When these objects are <i>immutable</i>, i.e. they do not modify its internal
  59 state except maybe for reattaching to a new set of state data, and some
  60 additional conditions are met, a very convenient optimization technique known
  61 as the <i>flyweight pattern</i> can be introduced.
  62 </p>
  63
  64 <p>
  65 Let us say there are <i>N</i> different objects living at a given time
  66 inside the application, globally taking <i>M</i> different values. If <i>N</i>
  67 is much greater than <i>M</i>, that is, there are many equivalent objects,
  68 we can eliminate the implicit redundancy by replacing the original objects with
  69 handle classes which refer to a common repository of shared value objects,
  70 as depicted in the figure. The handle objects or flyweights, which act as
  71 proxies for the actual values, typically occupy the size of a mere pointer.
  72 The larger the value classes, and the greater the <i>N</i>/<i>M</i> ratio,
  73 the more significant the memory savings achieved by this tecnhique. The
  74 classical example of application of the flyweight idiom is that of a word
  75 processor: each letter in the document carries a large wealth of
  76 information, such as its Unicode identifier, font, size, typesetting effects,
  77 etc., but given that the degree of letter repetition in a document is extremely
  78 high, implementing those letters as flyweight classes allows us to easily
  79 handle documents ranging in the hundreds of thousands of characters.
  80 </p>
  81
  82 <p>
  83 Most presentations of the design pattern found in the literature do make a
  84 distinction between the flyweight <i>intrinsic information</i> (the constant
  85 data factored out into the repository) and <i>extrinsic</i>, mutable
  86 information, which is stored along with the flyweight objects or passed
  87 externally. This separation analysis can have some merit from the point of
  88 view of application design, but when it comes to implementation extrinsic
  89 information has no impact on the overall flyweight scheme. So,
  90 Boost.Flyweight assumes that the type onto which the library operates
  91 entirely consists of intrinsic information: this allows for a particularly
  92 appealing realization of the idiom in C++ in which
  93 <code>flyweight&lt;T&gt;</code> is an opaque type convertible to
  94 <code>const T&amp;</code>.
  95 </p>
  96
  97 <p>
  98 The central repository of shared value objects is known as the <i>flyweight
  99 factory</i>. This component is able to locate and return a reference to an
 100 object with a given value, or insert the value if no copy was previously
 101 stored. Boost.Flyweight controls the interaction of flyweights with
 102 their factory transparently to the programmer, so that a casual user of the
 103 library need not even be concerned about the presence of such factory.
 104 Boost.Flyweight uses by default a factory based on a hashed container which
 105 is expected to be suitable for most situations. When this is not the case, it
 106 is possible to customize the factory or even replace it with another one of
 107 a different type, either provided by Boost.Flyweight or defined by the user.
 108 Other aspects of the implementation are also customizable and extendable.
 109 </p>
 110
 111 <h2 clear="all" style="clear: all;">
 112 <a name="namespace">Namespace</a>
 113 </h2>
 114
 115 <p>
 116 All the public types of Boost.Flyweight reside in namespace <code>::boost::flyweights</code>.
 117 Additionaly, the main class template <code>flyweight</code> is lifted to namespace
 118 <code>::boost</code> by means of a <code>using</code> declaration. For brevity of
 119 exposition, the fragments of code in the documentation are written as if the following
 120 directives were in effect:
 121 </p>
 122
 123 <blockquote><pre>
 124 <span class=keyword>using</span> <span class=keyword>namespace</span> <span class=special>::</span><span class=identifier>boost</span><span class=special>;</span>
 125 <span class=keyword>using</span> <span class=keyword>namespace</span> <span class=special>::</span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>flyweights</span><span class=special>;</span>
 126 </pre></blockquote>
 127
 128 <h2><a name="guide">Guide to the reader</a></h2>
 129
 130 <p>
 131 Although Boost.Flyweight features an extensive customization
 132 framework controlling many internal implementation aspects, the library is designed
 133 in such a way that most users need not be concerned about or
 134 even aware of the underlying complexity. Learning to use Boost.Flyweight
 135 as an off-the-shelf component can be acomplished merely by reading
 136 the <a href="basics.html">basics</a> section and skimming through the
 137 part on <a href="key_value.html">key-value flyweights</a>, the section on flyweight type
 138 <a href="configuration.html#tagging">tagging</a>  and the discussion of some
 139 <a href="technical.html">technical issues</a>. The
 140 <a href="configuration.html">configuration</a> section teaches how to fine tune the
 141 different internal components of the library. Only very advanced usage
 142 scenarios will require implementing user-provided pluggable components:
 143 this is covered on the <a href="extension.html">extension</a> section.
 144 </p>
 145
 146 <hr>
 147
 148 <div class="prev_link"><a href="../index.html"><img src="../prev.gif" alt="index" border="0"><br>
 149 Index
 150 </a></div>
 151 <div class="up_link"><a href="../index.html"><img src="../up.gif" alt="index" border="0"><br>
 152 Index
 153 </a></div>
 154 <div class="next_link"><a href="basics.html"><img src="../next.gif" alt="basics" border="0"><br>
 155 Basics
 156 </a></div><br clear="all" style="clear: all;">
 157
 158 <br>
 159
 160 <p>Revised August 13th 2008</p>
 161
 162 <p>&copy; Copyright 2006-2008 Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
 163 Distributed under the Boost Software
 164 License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt">
 165 LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
 166 http://www.boost.org/LICENSE_1_0.txt</a>)
 167 </p>
 168
 169 </body>
 170 </html>