[ceph.git] / ceph / src / boost / libs / flyweight / 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>
Commit	Line	Data
7c673cae FG	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<T></code> is an opaque type convertible to
94	<code>const T&</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>© Copyright 2006-2008 Joaquín M López Muñ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>