doc/tutorial/index.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0.1 Transitional//EN">

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Boost.Flyweight Documentation - Tutorial</title>
<link rel="stylesheet" href="../style.css" type="text/css">
<link rel="start" href="../index.html">
<link rel="prev" href="../index.html">
<link rel="up" href="../index.html">
<link rel="next" href="basics.html">
</head>

<body>
<h1><img src="../../../../boost.png" alt="Boost logo" align=
"middle" width="277" height="86">Boost.Flyweight Tutorial</h1>

<div class="prev_link"><a href="../index.html"><img src="../prev.gif" alt="index" border="0"><br>
Index
</a></div>
<div class="up_link"><a href="../index.html"><img src="../up.gif" alt="index" border="0"><br>
Index
</a></div>
<div class="next_link"><a href="basics.html"><img src="../next.gif" alt="basics" border="0"><br>
Basics
</a></div><br clear="all" style="clear: all;">

<hr>

<h2>Contents</h2>

<ul>
  <li><a href="#rationale">Rationale</a></li>
  <li><a href="#namespace">Namespace</a></li>
  <li><a href="#guide">Guide to the reader</a></li>
  <li><a href="basics.html">Basics</a></li>
  <li><a href="key_value.html">Key-value flyweights</a></li>
  <li><a href="configuration.html">Configuring Boost.Flyweight</a></li>
  <li><a href="extension.html">Extending Boost.Flyweight</a></li>
  <li><a href="technical.html">Technical issues</a></li>
  <li><a href="lambda_expressions.html">Annex: MPL Lambda expressions</a></li>
</ul>

<h2><a name="rationale">Rationale</a></h2>

<span style="float:left;margin-right:20px;margin-bottom:20px">
<p align="center">
<img src="flyweight_rep.png"
alt="representation of a flyweight scenario"
width="424" height="320"><br>
<b>Fig. 1: Representation of a flyweight scenario.</b>
</p>
</span>

<p>
Consider an application that has to manage large quantities of objects of
moderate size, potentially requiring more memory than reasonably available.
When these objects are <i>immutable</i>, i.e. they do not modify its internal
state except maybe for reattaching to a new set of state data, and some
additional conditions are met, a very convenient optimization technique known
as the <i>flyweight pattern</i> can be introduced.
</p>

<p>
Let us say there are <i>N</i> different objects living at a given time
inside the application, globally taking <i>M</i> different values. If <i>N</i>
is much greater than <i>M</i>, that is, there are many equivalent objects,
we can eliminate the implicit redundancy by replacing the original objects with
handle classes which refer to a common repository of shared value objects,
as depicted in the figure. The handle objects or flyweights, which act as
proxies for the actual values, typically occupy the size of a mere pointer.
The larger the value classes, and the greater the <i>N</i>/<i>M</i> ratio,
the more significant the memory savings achieved by this tecnhique. The
classical example of application of the flyweight idiom is that of a word
processor: each letter in the document carries a large wealth of
information, such as its Unicode identifier, font, size, typesetting effects,
etc., but given that the degree of letter repetition in a document is extremely
high, implementing those letters as flyweight classes allows us to easily
handle documents ranging in the hundreds of thousands of characters.
</p>

<p>
Most presentations of the design pattern found in the literature do make a
distinction between the flyweight <i>intrinsic information</i> (the constant
data factored out into the repository) and <i>extrinsic</i>, mutable
information, which is stored along with the flyweight objects or passed
externally. This separation analysis can have some merit from the point of
view of application design, but when it comes to implementation extrinsic
information has no impact on the overall flyweight scheme. So,
Boost.Flyweight assumes that the type onto which the library operates
entirely consists of intrinsic information: this allows for a particularly
appealing realization of the idiom in C++ in which
<code>flyweight&lt;T&gt;</code> is an opaque type convertible to
<code>const T&amp;</code>.
</p>

<p>
The central repository of shared value objects is known as the <i>flyweight
factory</i>. This component is able to locate and return a reference to an
object with a given value, or insert the value if no copy was previously
stored. Boost.Flyweight controls the interaction of flyweights with
their factory transparently to the programmer, so that a casual user of the
library need not even be concerned about the presence of such factory.
Boost.Flyweight uses by default a factory based on a hashed container which
is expected to be suitable for most situations. When this is not the case, it
is possible to customize the factory or even replace it with another one of
a different type, either provided by Boost.Flyweight or defined by the user.
Other aspects of the implementation are also customizable and extendable.
</p>

<h2 clear="all" style="clear: all;">
<a name="namespace">Namespace</a>
</h2>

<p>
All the public types of Boost.Flyweight reside in namespace <code>::boost::flyweights</code>.
Additionaly, the main class template <code>flyweight</code> is lifted to namespace
<code>::boost</code> by means of a <code>using</code> declaration. For brevity of
exposition, the fragments of code in the documentation are written as if the following
directives were in effect:
</p>

<blockquote><pre>
<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=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>
</pre></blockquote>

<h2><a name="guide">Guide to the reader</a></h2>

<p>
Although Boost.Flyweight features an extensive customization
framework controlling many internal implementation aspects, the library is designed
in such a way that most users need not be concerned about or
even aware of the underlying complexity. Learning to use Boost.Flyweight
as an off-the-shelf component can be acomplished merely by reading
the <a href="basics.html">basics</a> section and skimming through the
part on <a href="key_value.html">key-value flyweights</a>, the section on flyweight type
<a href="configuration.html#tagging">tagging</a>  and the discussion of some
<a href="technical.html">technical issues</a>. The
<a href="configuration.html">configuration</a> section teaches how to fine tune the
different internal components of the library. Only very advanced usage
scenarios will require implementing user-provided pluggable components:
this is covered on the <a href="extension.html">extension</a> section.
</p>

<hr>

<div class="prev_link"><a href="../index.html"><img src="../prev.gif" alt="index" border="0"><br>
Index
</a></div>
<div class="up_link"><a href="../index.html"><img src="../up.gif" alt="index" border="0"><br>
Index
</a></div>
<div class="next_link"><a href="basics.html"><img src="../next.gif" alt="basics" border="0"><br>
Basics
</a></div><br clear="all" style="clear: all;">

<br>

<p>Revised August 13th 2008</p>

<p>&copy; Copyright 2006-2008 Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
Distributed under the Boost Software
License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt">
LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
http://www.boost.org/LICENSE_1_0.txt</a>)
</p>

</body>
</html>