Boost-Commit :

Date view	Thread view	Subject view	Author view

From: joaquin_at_[hidden]
Date: 2007-12-17 16:38:58

Author: joaquin
Date: 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
New Revision: 42134
URL: http://svn.boost.org/trac/boost/changeset/42134

Log:
updated December 17th 2007
Added:
   sandbox/flyweight/libs/flyweight/doc/tests.html (contents, props changed)
   sandbox/flyweight/libs/flyweight/doc/tutorial/technical.html (contents, props changed)
   sandbox/flyweight/libs/flyweight/example/custom_factory.cpp (contents, props changed)
   sandbox/flyweight/libs/flyweight/test/test_init.cpp (contents, props changed)
   sandbox/flyweight/libs/flyweight/test/test_init.hpp (contents, props changed)
   sandbox/flyweight/libs/flyweight/test/test_init_main.cpp (contents, props changed)
Text files modified:
   sandbox/flyweight/boost/flyweight/detail/flyweight_core.hpp | 6 +
   sandbox/flyweight/boost/flyweight/flyweight.hpp | 12 ++++
   sandbox/flyweight/libs/flyweight/doc/acknowledgements.html | 14 ++--
   sandbox/flyweight/libs/flyweight/doc/examples.html | 26 ++++++++--
   sandbox/flyweight/libs/flyweight/doc/index.html | 4
   sandbox/flyweight/libs/flyweight/doc/reference/factories.html | 4
   sandbox/flyweight/libs/flyweight/doc/reference/flyweight.html | 72 +++++++++++++++++++++++++++--
   sandbox/flyweight/libs/flyweight/doc/reference/index.html | 2
   sandbox/flyweight/libs/flyweight/doc/tutorial/configuration.html | 29 +++++++----
   sandbox/flyweight/libs/flyweight/doc/tutorial/extension.html | 99 +++++++++++++++++++++++++++++++++++----
   sandbox/flyweight/libs/flyweight/doc/tutorial/index.html | 3
   sandbox/flyweight/libs/flyweight/doc/tutorial/lambda_expressions.html | 12 ++--
   sandbox/flyweight/libs/flyweight/example/Jamfile.v2 | 5 ++
   sandbox/flyweight/libs/flyweight/test/Jamfile.v2 | 1
   sandbox/flyweight/libs/flyweight/test/test_all_main.cpp | 2
   15 files changed, 237 insertions(+), 54 deletions(-)

Modified: sandbox/flyweight/boost/flyweight/detail/flyweight_core.hpp
==============================================================================
--- sandbox/flyweight/boost/flyweight/detail/flyweight_core.hpp (original)
+++ sandbox/flyweight/boost/flyweight/detail/flyweight_core.hpp 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
@@ -112,6 +112,8 @@
 typedef typename LockingPolicy::mutex_type mutex_type;
 typedef typename LockingPolicy::lock_type lock_type;

+ static bool init(){return &(factory())!=0;}
+
 static handle_type insert(const Value& x)
 {
 lock_type lock(mutex());
@@ -159,9 +161,9 @@
bool flyweight_core<
 Value,Tag,TrackingPolicy,
 FactorySpecifier,LockingPolicy,HolderSpecifier>::static_force_holder_get=
- &flyweight_core<
+ &(flyweight_core<
 Value,Tag,TrackingPolicy,
- FactorySpecifier,LockingPolicy,HolderSpecifier>::holder_type::get()!=0;
+ FactorySpecifier,LockingPolicy,HolderSpecifier>::holder_type::get())!=0;

} /* namespace flyweights::detail */

Modified: sandbox/flyweight/boost/flyweight/flyweight.hpp
==============================================================================
--- sandbox/flyweight/boost/flyweight/flyweight.hpp (original)
+++ sandbox/flyweight/boost/flyweight/flyweight.hpp 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
@@ -143,6 +143,18 @@
public:
   typedef T value_type;

+ /* static data initialization */
+
+ static bool init(){return core::init();}
+
+ class initializer
+ {
+ public:
+ initializer():b(init()){}
+ private:
+ bool b;
+ };
+
   /* construct/copy/destroy */

   flyweight():h(core::insert(T())){}

Modified: sandbox/flyweight/libs/flyweight/doc/acknowledgements.html
==============================================================================
--- sandbox/flyweight/libs/flyweight/doc/acknowledgements.html (original)
+++ sandbox/flyweight/libs/flyweight/doc/acknowledgements.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
@@ -6,7 +6,7 @@
<title>Boost.Flyweight Documentation - Acknowledgements</title>
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="start" href="index.html">
-<link rel="prev" href="xxx.html">
+<link rel="prev" href="tests.html">
<link rel="up" href="index.html">
</head>

@@ -14,8 +14,8 @@
<h1><img src="../../../boost.png" alt="boost.png (6897 bytes)" align=
"middle" width="277" height="86">Boost.Flyweight Acknowledgements</h1>

-<div class="prev_link"><a href="xxx.html"><img src="prev.gif" alt="xxx" border="0"> 
-[not linked yet]
+<div class="prev_link"><a href="tests.html"><img src="prev.gif" alt="tests" border="0"> 
+Tests
</a></div>
<div class="up_link"><a href="index.html"><img src="up.gif" alt="index" border="0"> 
Index
@@ -29,7 +29,7 @@


The following people has provided valuable feedback and suggestions during the
-development of the library: Janek Kozicki, Tobias Schwinger,
+development of the library: Ion Gaztañaga, Janek Kozicki, Tobias Schwinger,
Pavel Voženílek. Rosa Bernárdez has proofread the
documentation from the first drafts up to its present form.

@@ -52,8 +52,8 @@

<hr>

-<div class="prev_link"><a href="xxx.html"><img src="prev.gif" alt="xxx" border="0"> 
-[not linked yet]
+<div class="prev_link"><a href="tests.html"><img src="prev.gif" alt="tests" border="0"> 
+Tests
</a></div>
<div class="up_link"><a href="index.html"><img src="up.gif" alt="index" border="0"> 
Index
@@ -63,7 +63,7 @@

 

-Revised August 16th 2007
+Revised November 27th 2007

© Copyright 2006-2007 Joaquín M López Muñoz.
Distributed under the Boost Software

Modified: sandbox/flyweight/libs/flyweight/doc/examples.html
==============================================================================
--- sandbox/flyweight/libs/flyweight/doc/examples.html (original)
+++ sandbox/flyweight/libs/flyweight/doc/examples.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
@@ -8,7 +8,7 @@
<link rel="start" href="index.html">
<link rel="prev" href="xxx.html">
<link rel="up" href="index.html">
-<link rel="next" href="xxx.html">
+<link rel="next" href="tests.html">
</head>

<body>
@@ -21,8 +21,8 @@
<div class="up_link"><a href="index.html"><img src="up.gif" alt="index" border="0"> 
Index
</a></div>
-<div class="next_link"><a href="xxx.html"><img src="next.gif" alt="xxx" border="0"> 
-[not linked yet]
+<div class="next_link"><a href="tests.html"><img src="next.gif" alt="tests" border="0"> 
+Tests
</a></div> 
 

@@ -38,6 +38,7 @@
 <li>Example 3: formatted text processing</li>
 <li>Example 4: serialization</li>
 <li>Example 5: performance comparison</li>
+ <li>Example 6: custom factory</li>
</ul>

<h2><a name="example1">Example 1: basic usage</a></h2>
@@ -183,6 +184,18 @@
allocators that keep track of the allocations and deallocations requested.


+<h2><a name="example6">Example 6: custom factory</a></h2>
+
+
+See source code.
+
+
+
+The example shows how to write and use a custom factory class. This
+"verbose" factory outputs messages tracing the invocations of its public interface
+by Boost.Flyweight, so helping the user visualize factory usage patterns.
+
+
<hr>

<div class="prev_link"><a href="xxx.html"><img src="prev.gif" alt="xxx" border="0"> 
@@ -191,13 +204,14 @@
<div class="up_link"><a href="index.html"><img src="up.gif" alt="index" border="0"> 
Index
</a></div>
-<div class="next_link"><a href="xxx.html"><img src="next.gif" alt="xxx" border="0"> 
-[not linked yet]
+<div class="next_link"><a href="tests.html"><img src="next.gif" alt="tests" border="0"> 
+Tests
</a></div> 
 
+
 

-Revised November 12th 2007
+Revised November 29th 2007

© Copyright 2006-2007 Joaquín M López Muñoz.
Distributed under the Boost Software

Modified: sandbox/flyweight/libs/flyweight/doc/index.html
==============================================================================
--- sandbox/flyweight/libs/flyweight/doc/index.html (original)
+++ sandbox/flyweight/libs/flyweight/doc/index.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
@@ -55,7 +55,7 @@
 <li>Reference</li>
 <li>[more to come]</li>
 <li>Examples</li>
- <li>[more to come]</li>
+ <li>Tests</li>
 <li>Acknowledgements</li>
</ul>

@@ -69,7 +69,7 @@

 

-Revised September 20th 2007
+Revised November 27th 2007

© Copyright 2006-2007 Joaquín M López Muñoz.
Distributed under the Boost Software

Modified: sandbox/flyweight/libs/flyweight/doc/reference/factories.html
==============================================================================
--- sandbox/flyweight/libs/flyweight/doc/reference/factories.html (original)
+++ sandbox/flyweight/libs/flyweight/doc/reference/factories.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
@@ -137,7 +137,7 @@



-Additionally to the basic thread-safety guarantee which is implicitly assumed
+Additionally to the basic thread safety guarantee which is implicitly assumed
for most classes including the majority of components of the
C++ standard library, it is required that the member function <code>entry</code>
can be invoked simultaneously from different threads, even in the presence
@@ -568,7 +568,7 @@

 

-Revised September 26th 2007
+Revised November 26th 2007

© Copyright 2006-2007 Joaquín M López Muñoz.
Distributed under the Boost Software

Modified: sandbox/flyweight/libs/flyweight/doc/reference/flyweight.html
==============================================================================
--- sandbox/flyweight/libs/flyweight/doc/reference/flyweight.html (original)
+++ sandbox/flyweight/libs/flyweight/doc/reference/flyweight.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
@@ -41,6 +41,7 @@
 <li>Class template flyweight
 <ul>
 <li>Instantiation types</li>
+ <li>Static data initialization</li>
 <li>Constructors, copy and assignment</li>
 <li>Convertibility to the underlying type</li>
 <li>Modifiers</li>
@@ -167,14 +168,15 @@



-<code>flyweight</code> is parameterized according to the following aspects:
+<code>flyweight</code> is parameterized according to some aspects:
<ul>
 <li>The factory class used to store
 and retrieve the shared value objects.
 </li>
 <li>The type of holder used to
- instantiate the flyweight factory, which is unique for each
- specialization of the <code>flyweight</code> class template.
+ instantiate the flyweight factory and a mutex object, both of
+ which are unique to each specialization of the <code>flyweight</code>
+ class template.
 </li>
 <li>A locking policy determining
 the synchronization mechanisms for internal access to shared resources.
@@ -184,6 +186,31 @@
 destroyed.
 </li>
</ul>
+These aspects impact the internal structure and behavior
+of the <code>flyweight</code> instantiation in the following manner:
+<ul>
+ <li>Each instantation of <code>flyweight</code> internally owns
+ a unique factory object and a unique synchronization
+ mutex object, both of which
+ are created through the use of an associated holder type.
+ </li>
+ <li>The flyweight factory stores elements of an undisclosed type
+ <code>Entry</code> that is implicitly convertible to
+ <code>const T&</code>. Every flyweight object is associated
+ to a <code>const T</code> reference resulting from the conversion
+ from some <code>Entry</code> stored in the factory.
+ </li>
+ <li>The associated mutex object is used to protect all invocations
+ to the insertion and deletion functions of the internal flyweight
+ factory.
+ </li>
+ <li>Each flyweight object internally stores a value of some
+ undisclosed type <code>Handle</code>. <code>Handle</code> and
+ the <code>Entry</code> type referred to above are obtained
+ from invocations to the associated tracking policy, in the
+ manner described for this concept.
+ </li>
+</ul>
In what follows, we implicitly assume that <code>T</code> equivalence
refers to the equivalence relationship induced by the factory class used.

@@ -198,6 +225,11 @@
public:
 typedef T value_type;

+ // static data initialization:
+
+ static bool init();
+ class initializer{public:initializer();};
+
 // construct/copy/destroy:

 flyweight();
@@ -246,7 +278,12 @@
 <li>a locking policy,</li>
 <li>a tracking policy.</li>
</ul>
-No aspect can be specified twice. The default configuration arguments are:
+No aspect can be specified twice. Each internal component of the
+<code>flyweight</code> instantiation is obtained through use of the
+corresponding specifier; for instance, the factory results from a
+certain (MPL) invocation of the given factory specifier, the internal
+mutex from the given locking policy, etc.
+The default configuration arguments are:
<ul>
 <li>No tagging,</li>
 <li>hashed_factory<>,</li>
@@ -256,6 +293,31 @@
</ul>


+<h4><a name="static_init">Static data initialization</a></h4>
+
+
+The static data internal to a given <code>flyweight</code> instantiation
+(factory instance, etc.) is constructed during the dynamic initialization
+phase of the program or just before the first program-wide use of the
+instantiated class, whichever comes first. The following utilities can be
+used when more control about the moment of construction is required.
+
+
+<code>static bool init();</code>
+
+<blockquote>
+Effects: After execution of this function the static data associated
+to the instantiation of <code>flyweight</code> is guaranteed to be
+constructed. 
+Note: Concurrent execution of this function is not thread safe.
+</blockquote>
+
+<code>initializer::initializer();</code>
+
+<blockquote>
+Effects: Executes <code>init()</code>.
+</blockquote>
+
<h4><a name="constructors">Constructors, copy and assignment</a></h4>

<code>flyweight();</code>
@@ -548,7 +610,7 @@

 

-Revised September 26th 2007
+Revised December 17th 2007

© Copyright 2006-2007 Joaquín M López Muñoz.
Distributed under the Boost Software

Modified: sandbox/flyweight/libs/flyweight/doc/reference/index.html
==============================================================================
--- sandbox/flyweight/libs/flyweight/doc/reference/index.html (original)
+++ sandbox/flyweight/libs/flyweight/doc/reference/index.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
@@ -6,7 +6,7 @@
<title>Boost.Flyweight Documentation - Reference</title>
<link rel="stylesheet" href="../style.css" type="text/css">
<link rel="start" href="../index.html">
-<link rel="prev" href="xxx.html">
+<link rel="prev" href="lambda_expressions.html">
<link rel="up" href="../index.html">
<link rel="next" href="../tutorial/lambda_expressions.html">
</head>

Added: sandbox/flyweight/libs/flyweight/doc/tests.html
==============================================================================
--- (empty file)
+++ sandbox/flyweight/libs/flyweight/doc/tests.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007)
@@ -0,0 +1,119 @@
+<!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 - Tests</title>
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="start" href="index.html">
+<link rel="prev" href="examples.html">
+<link rel="up" href="index.html">
+<link rel="next" href="acknowledgements.html">
+</head>
+
+<body>
+<h1><img src="../../../boost.png" alt="boost.png (6897 bytes)" align=
+"middle" width="277" height="86">Boost.Flyweight Tests</h1>
+
+<div class="prev_link"><a href="examples.html"><img src="prev.gif" alt="examples" border="0"> 
+Examples
+</a></div>
+<div class="up_link"><a href="index.html"><img src="up.gif" alt="index" border="0"> 
+Index
+</a></div>
+<div class="next_link"><a href="acknowledgements.html"><img src="next.gif" alt="acknowledgements" border="0"> 
+Acknowledgements
+</a></div> 
+
+<hr>
+
+
+The Boost.Flyweight test suite exercises the whole spectrum of
+functionalities provided by the library. Although the tests are not meant
+to serve as a learning guide, the interested reader may find it
+useful to inspect the source code to gain familiarity with the usage
+of Boost.Flyweight.
+
+
+
+<table cellspacing="0" cellpadding="5">
+ <caption>Boost.Flyweight test suite.</caption>
+<tr>
+ <th>Program</th>
+ <th>Description</th>
+</tr>
+<tr>
+ <td>test_assoc_cont_factory.cpp</td>
+ <td>assoc_container_factory
+ factory specifier.</td>
+</tr>
+<tr class="odd_tr">
+ <td>test_basic.cpp</td>
+ <td>Exercises the default components of <code>flyweight</code>.</td>
+</tr>
+<tr>
+ <td>test_custom_factory.cpp</td>
+ <td>Creates a user-defined factory class and specifier.</td>
+</tr>
+<tr class="odd_tr">
+ <td>test_init.cpp</td>
+ <td>Boost.Flyweight <a href="tutorial/technical.html#static_init">static
+ data initialization</a> facilities.</td>
+</tr>
+<tr>
+ <td>test_intermod_holder.cpp 
+ intermod_holder_dll.cpp</td>
+ <td>Exercises intermodule_holder.</td> +</tr> +<tr class="odd_tr"> + <td>test_multictor.cpp</td> + <td>Tests <code>flyweight</code> <a href="reference/flyweight.html#constructors">multiple + argument constructors</a>.</td> +</tr> +<tr> + <td>test_no_locking.cpp</td> + <td>no_locking policy.</td> +</tr> +<tr class="odd_tr"> + <td>test_no_tracking.cpp</td> + <td>no_tracking policy.</td> +</tr> +<tr> + <td>test_serialization.cpp</td> + <td>Exercises <code>flyweight</code> <a href="tutorial/basics.html#serialization">serialization + capabilities</a>.</td> +</tr> +<tr class="odd_tr"> + <td>test_set_factory.cpp</td> + <td>set_factory + factory specifier.</td> +</tr> +</table> + + +<hr> + +<div class="prev_link"><a href="examples.html"><img src="prev.gif" alt="examples" border="0"> +Examples +</a></div> +<div class="up_link"><a href="index.html"><img src="up.gif" alt="index" border="0"> +Index +</a></div> +<div class="next_link"><a href="acknowledgements.html"><img src="next.gif" alt="acknowledgements" border="0"> +Acknowledgements +</a></div> + + + + +Revised November 27th 2007 + +© Copyright 2006-2007 Joaquín M López Muñ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>) + + +</body> +</html>

Modified: sandbox/flyweight/libs/flyweight/doc/tutorial/configuration.html ============================================================================== --- sandbox/flyweight/libs/flyweight/doc/tutorial/configuration.html (original) +++ sandbox/flyweight/libs/flyweight/doc/tutorial/configuration.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -123,6 +123,7 @@ #include <boost/flyweight/flyweight.hpp> // class template flyweight #include <boost/flyweight/hashed_factory.hpp> // hashed flyweight factory #include <boost/flyweight/static_holder.hpp> // regular factory instantiation +#include <boost/flyweight/simple_locking.hpp> // simple locking policy #include <boost/flyweight/refcounted.hpp> // refcounting tracking policy </pre></blockquote> @@ -541,16 +542,22 @@ No flyweight tracking is done when this policy is selected, which implies that the values stored in the factory remain in it until program termination. -In comparison with <code>refcounted</code>, <code>no_tracking</code> -produces flyweight objects which are faster to pass -around and it also results in some reduction in memory usage due to the -absence of reference counters. The most obvious drawback is that -the number of unused entries stored in the factory can keep growing -during the program lifetime, which can become a problem for certain -patterns of flyweight creation where the set of active values "drifts" -over time. Another drawback is a potential delay during program -termination, since it is then when all the factory entries get destroyed -at once. +As compared with <code>refcounted</code>, <code>no_tracking</code> presents +advantages and drawbacks. The benefits are: +<ul> + <li>Non-tracked flyweight objects are faster to pass around than refcounted ones.</li> + <li>There is some in some reduction in memory usage due to the + absence of reference counters.</li> +</ul> +whereas potential drawbacks of using <code>no_tracking</code> include: +<ul> + <li>The number of unused entries stored in the factory can keep growing + during the program lifetime, which can become a problem for certain + patterns of flyweight creation where the set of active values "drifts" + over time.</li> + <li>There can be a potential delay during program termination, since + it is then when all the factory entries get destroyed at once.</li> +</ul> <hr> @@ -567,7 +574,7 @@ -Revised August 16th 2007 +Revised November 29th 2007 © Copyright 2006-2007 Joaquín M López Muñoz. Distributed under the Boost Software

Modified: sandbox/flyweight/libs/flyweight/doc/tutorial/extension.html ============================================================================== --- sandbox/flyweight/libs/flyweight/doc/tutorial/extension.html (original) +++ sandbox/flyweight/libs/flyweight/doc/tutorial/extension.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -8,7 +8,7 @@ <link rel="start" href="../index.html"> <link rel="prev" href="configuration.html"> <link rel="up" href="index.html"> -<link rel="next" href="lambda_expressions.html"> +<link rel="next" href="technical.html"> </head> <body> @@ -21,8 +21,8 @@ <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight tutorial" border="0"> Boost.Flyweight tutorial </a></div> -<div class="next_link"><a href="lambda_expressions.html"><img src="../next.gif" alt="annex: MPL lambda expressions" border="0"> -Annex: MPL lambda expressions +<div class="next_link"><a href="technical.html"><img src="../next.gif" alt="technical issues" border="0"> +Technical issues </a></div> <hr> @@ -68,8 +68,8 @@ <code>static_holder_class</code> is a class template, so a specifier can be seen as a convenient way to provide access to a family of related concrete components (the different possible instantiations of the class template): -<code>flyweight</code> internally selects the concrete component -appropriate for its internal types. +<code>flyweight</code> internally selects the particular component +appropriate for its internal needs. <h2><a name="factories">Custom factories</a></h2> @@ -116,6 +116,79 @@ +Let us see an actual example of realization of a custom factory class. Suppose +we want to trace the different invocations by Boost.Flyweight of the +<code>insert()</code> and <code>erase()</code> member functions: this can be +done by using a custom factory whose member methods emit trace messages +to the program console. We base the implementation of the repository +functionality on a regular <code>std::set</code>: + +<blockquote><pre> +template<typename Entry,typename Value> +class verbose_factory_class +{ + typedef std::set<Entry,std::less<Value> > store_type; + + store_type store; + +public: + typedef typename store_type::iterator handle_type; + + handle_type insert(const Entry& x) + { + std::pair<handle_type, bool> p=store.insert(x); + if(p.second){ /* new entry */ + std::cout<<"new: "<<(const Value&)x<<std::endl; + } + else{ /* existing entry */ + std::cout<<"hit: "<<(const Value&)x<<std::endl; + } + return p.first; + } + + void erase(handle_type h) + { + std::cout<<"del: "<<(const Value&)*h<<std::endl; + store.erase(h); + } + + const Entry& entry(handle_type h) + { + return *h; + } +}; +</pre></blockquote> + + +The code deserves some commentaries: +<ul> + <li> + Note that the factory is parameterized by <code>Entry</code> + and <code>Value</code>, as these types are provided internally by Boost.Flyweight + when the factory is instantiated as part of the machinery of <code>flyeight</code>; + but there is nothing to prevent us from having more template parameters for + finer configuration of the factory type: for instance, we could extend + <code>verbose_factory_class</code> to accept some comparison predicate rather than + the default <code>std::less<Value></code>, or to specify the allocator + used by the internal <code>std::set</code>. + </li> + <li> + The fact that <code>Entry</code> is convertible to <code>const Value&</code> + (which is about the only property known about <code>Entry</code>) is + exploited in the specification of <code>std::less<Value&gt</code> as + the comparison predicate for the <code>std::set</code> of <code>Entry</code>s + used as the internal repository. + </li> + <li> + As our public <code>handle_type</code> we are simply using an iterator to the + internal <code>std::set</code>. + </li> +</ul> + + + +In order to plug a custom factory into the specification of a <code>flyweight</code> +type, we need an associated construct called the factory specifier. A factory specifier is a <a href="lambda_expressions.html"><code>Lambda Expression</code></a> accepting the two argument types <code>Entry</code> @@ -197,6 +270,11 @@ </ol> + +Example 6 in the examples section develops +in full the <code>verbose_factory_class</code> case sketched above. + + <h2><a name="holders">Custom holders</a></h2> @@ -443,9 +521,8 @@ </pre></blockquote> -Note that a tracking policy is its own specifier, i.e. there is no -additional class to be passed as a proxy for the real component as is -the case with factories and holders. +Tracking policies are their own specifiers, that is, they are provided directly +as template arguments to the <code>flyweight</code> class template. <hr> @@ -456,13 +533,13 @@ <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight tutorial" border="0"> Boost.Flyweight tutorial </a></div> -<div class="next_link"><a href="lambda_expressions.html"><img src="../next.gif" alt="annex: MPL lambda expressions" border="0"> -Annex: MPL lambda expressions +<div class="next_link"><a href="technical.html"><img src="../next.gif" alt="technical issues" border="0"> +Technical issues </a></div> -Revised September 11th 2007 +Revised November 29th 2007 © Copyright 2006-2007 Joaquín M López Muñoz. Distributed under the Boost Software

Modified: sandbox/flyweight/libs/flyweight/doc/tutorial/index.html ============================================================================== --- sandbox/flyweight/libs/flyweight/doc/tutorial/index.html (original) +++ sandbox/flyweight/libs/flyweight/doc/tutorial/index.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -37,6 +37,7 @@ <li>Basics</li> <li>Configuring Boost.Flyweight</li> <li>Extending Boost.Flyweight</li> + <li>Technical issues</li> <li>Annex: MPL Lambda expressions</li> </ul> @@ -138,7 +139,7 @@ -Revised August 16th 2007 +Revised November 26th 2007 © Copyright 2006-2007 Joaquín M López Muñoz. Distributed under the Boost Software

Modified: sandbox/flyweight/libs/flyweight/doc/tutorial/lambda_expressions.html ============================================================================== --- sandbox/flyweight/libs/flyweight/doc/tutorial/lambda_expressions.html (original) +++ sandbox/flyweight/libs/flyweight/doc/tutorial/lambda_expressions.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -6,7 +6,7 @@ <title>Boost.Flyweight Documentation - Tutorial - Annex - MPL lambda expressions</title> <link rel="stylesheet" href="../style.css" type="text/css"> <link rel="start" href="../index.html"> -<link rel="prev" href="extension.html"> +<link rel="prev" href="technical.html"> <link rel="up" href="index.html"> <link rel="next" href="../reference/index.html"> </head> @@ -15,8 +15,8 @@ <h1><img src="../../../../boost.png" alt="boost.png (6897 bytes)" align= "middle" width="277" height="86">Boost.Flyweight Tutorial Annex: MPL lambda expressions</h1> -<div class="prev_link"><a href="extension.html"><img src="../prev.gif" alt="extending Boost.Flyweight" border="0"> -Extending Boost.Flyweight +<div class="prev_link"><a href="technical.html"><img src="../prev.gif" alt="technical issues" border="0"> +Technical issues </a></div> <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight tutorial" border="0"> Boost.Flyweight tutorial @@ -155,8 +155,8 @@ <hr> -<div class="prev_link"><a href="extension.html"><img src="../prev.gif" alt="extending Boost.Flyweight" border="0"> -Extending Boost.Flyweight +<div class="prev_link"><a href="technical.html"><img src="../prev.gif" alt="technical issues" border="0"> +Technical issues </a></div> <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight tutorial" border="0"> Boost.Flyweight tutorial @@ -167,7 +167,7 @@ -Revised August 16th 2007 +Revised November 27th 2007 © Copyright 2006-2007 Joaquín M López Muñoz. Distributed under the Boost Software

Added: sandbox/flyweight/libs/flyweight/doc/tutorial/technical.html ============================================================================== --- (empty file) +++ sandbox/flyweight/libs/flyweight/doc/tutorial/technical.html 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -0,0 +1,162 @@ +<!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 - Technical issues</title> +<link rel="stylesheet" href="../style.css" type="text/css"> +<link rel="start" href="../index.html"> +<link rel="prev" href="extension.html"> +<link rel="up" href="index.html"> +<link rel="next" href="lambda_expressions.html"> +</head> + +<body> +<h1><img src="../../../../boost.png" alt="boost.png (6897 bytes)" align= +"middle" width="277" height="86">Boost.Flyweight Tutorial: Technical issues</h1> + +<div class="prev_link"><a href="extension.html"><img src="../prev.gif" alt="extending Boost.Flyweight" border="0"> +Extending Boost.Flyweight +</a></div> +<div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight tutorial" border="0"> +Boost.Flyweight tutorial +</a></div> +<div class="next_link"><a href="lambda_expressions.html"><img src="../next.gif" alt="annex: MPL lambda expressions" border="0"> +Annex: MPL lambda expressions +</a></div> + +<hr> + +<h3 align="center">Disclaimer: Boost.Flyweight is not a Boost library</h3> + +<h2>Contents</h2> + +<ul> + <li>Static data initialization</li> +</ul> + +<h2><a name="static_init">Static data initialization</a></h2> + + +For any given <code>T</code>, the type <code>flyweight<T></code> +maintains some class-wide or static data that needs to be properly +initialized before the class can be used. The internal machinery of +Boost.Flyweight guarantees that static data initialization +takes place automatically before the first use of the particular +<code>flyweight<T></code> instantiation in the program, and in +any case always during the so-called dynamic initialization phase +of the program startup sequence. Although this is not strictly +required by the C++ standard, in current practice dynamic initialization +is completed before <code>main()</code> begins. + + + +So, for all practical purposes, static data initialization is performed +before <code>main()</code> or before the first pre-<code>main()</code> +usage of the class, for instance if we declare a global +<code>static flyweight<T></code> object. This covers the vast +majority of usage cases in a transparent manner, but there are +exotic scenarios where the automatic static data initialization +policy of Boost.Flyweight can fail: + + +<blockquote><pre> +// global thread pool + +class thread_pool +{ +public: + thread_pool() + { + for(int i=0;i<100;++i)p[i]=shared_ptr<thread>(new thread(thread_fun)); + } + +private: + static void thread_fun() + { + // uses flyweight<std::string> + } + array<shared_ptr<thread>,100> p; +}; + +static thread_pool thpool; + +int main() +{ + ... +</pre></blockquote> + + +The global pool of the example launches several threads, each of which +internally uses <code>flyweight<std::string></code>. +Static data initialization can potentially be executed twice concurrently +if two threads happen to collide on the first usage of +<code>flyweight<std::string></code>: Boost.Flyweight initialization +does not consider thread safety. So, we need to explicitly take care of +static data initialization in a thread safe context before launching +the threads: + + +<blockquote><pre> +class thread_pool +{ +public: + thread_pool() + { + flyweight<std::string>::init(); + for(int i=0;i<100;++i)p[i]=shared_ptr<thread>(new thread(thread_fun)); + } + ... +</pre></blockquote> + + +The static member function <code>init</code> is not thread safe, either: in our particular +example it just happens to be called in a single threaded environment. +When concurrency can happen, <code>flyweight<T>::init</code> must +be properly synchronized by the programmer by using some mutual exclusion +mechanisms of her own. + + + +In some settings, particularly when defining global objects, calling +the function <code>flyweight<T>::init</code> can be a little +cumbersome. <code>flyweight<T></code> provides a nested type +<code>initializer</code> to do that job for us: + + +<blockquote><pre> +class thread_pool +{ + ... +}; + +// equivalent to calling flyweight<std::string>::init() +static flyweight<std::string>::initializer fwinit; +static thread_pool thpool; +</pre></blockquote> + +<hr> + +<div class="prev_link"><a href="extension.html"><img src="../prev.gif" alt="extending Boost.Flyweight" border="0"> +Extending Boost.Flyweight +</a></div> +<div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight tutorial" border="0"> +Boost.Flyweight tutorial +</a></div> +<div class="next_link"><a href="lambda_expressions.html"><img src="../next.gif" alt="annex: MPL lambda expressions" border="0"> +Annex: MPL lambda expressions +</a></div> + + + +Revised November 27th 2007 + +© Copyright 2006-2007 Joaquín M López Muñ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>) + + +</body> +</html>

Modified: sandbox/flyweight/libs/flyweight/example/Jamfile.v2 ============================================================================== --- sandbox/flyweight/libs/flyweight/example/Jamfile.v2 (original) +++ sandbox/flyweight/libs/flyweight/example/Jamfile.v2 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -17,6 +17,11 @@ : <include>$(BOOST_ROOT) ; +exe custom_factory + : custom_factory.cpp + : <include>$(BOOST_ROOT) + ; + exe html : html.cpp : <include>$(BOOST_ROOT)

Added: sandbox/flyweight/libs/flyweight/example/custom_factory.cpp ============================================================================== --- (empty file) +++ sandbox/flyweight/libs/flyweight/example/custom_factory.cpp 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -0,0 +1,122 @@ +/* Boost.Flyweight example of custom factory. + * + * Copyright 2006-2007 Joaquín M López Muñoz. + * Distributed under the Boost Software License, Version 1.0. + * (See accompanying file LICENSE_1_0.txt or copy at + * http://www.boost.org/LICENSE_1_0.txt) + * + * See http://www.boost.org/libs/flyweight for library home page. + */ + +/* We include the default components of Boost.Flyweight except the factory, + * which will be provided by ourselves. + */ +#include <boost/flyweight/flyweight.hpp> +#include <boost/flyweight/factory_tag.hpp> +#include <boost/flyweight/static_holder.hpp> +#include <boost/flyweight/simple_locking.hpp> +#include <boost/flyweight/refcounted.hpp> +#include <boost/tokenizer.hpp> +#include <functional> +#include <iostream> +#include <set> + +using namespace boost::flyweights; + +/* custom factory based on std::set with some logging capabilities */ + +/* Entry is the type of the stored objects. Value is the type + * on which flyweight operates, that is, the T in flyweoght<T>. It + * is guaranteed that Entry implicitly converts to const Value&. + * The factory class could accept other template arguments (for + * instance, a comparison predicate for the values), we leave it like + * that for simplicity. + */ + +template<typename Entry,typename Value> +class verbose_factory_class +{ + /* Entry store. Since Entry is implicitly convertible to const Value&, + * we can directly use std::less<Value> as the comparer for std::set. + */ + + typedef std::set<Entry,std::less<Value> > store_type; + + store_type store; + +public: + typedef typename store_type::iterator handle_type; + + handle_type insert(const Entry& x) + { + /* locate equivalent entry or insert otherwise */ + + std::pair<handle_type, bool> p=store.insert(x); + if(p.second){ /* new entry */ + std::cout<<"new: "<<(const Value&)x<<std::endl; + } + else{ /* existing entry */ + std::cout<<"hit: "<<(const Value&)x<<std::endl; + } + return p.first; + } + + void erase(handle_type h) + { + std::cout<<"del: "<<(const Value&)*h<<std::endl; + store.erase(h); + } + + const Entry& entry(handle_type h) + { + return *h; /* handle_type is an iterator */ + } +}; + +/* Specifier for verbose_factory_class. The simplest way to tag + * this struct as a factory specifier, so that flyweight<> accepts it + * as such, is by deriving from boost::flyweights::factory_marker. + * See the documentation for info on alternative tagging methods. + */ + +struct verbose_factory: factory_marker +{ + template<typename Entry,typename Value> + struct apply + { + typedef verbose_factory_class<Entry,Value> type; + } ; +}; + +/* ready to use it */ + +typedef flyweight<std::string,verbose_factory> fw_string; + +int main() +{ + typedef boost::tokenizer<boost::char_separator<char> > text_tokenizer; + + + std::string text= + "I celebrate myself, and sing myself, " + "And what I assume you shall assume, " + "For every atom belonging to me as good belongs to you. " + + "I loafe and invite my soul, " + "I lean and loafe at my ease observing a spear of summer grass. " + + "My tongue, every atom of my blood, form'd from this soil, this air, " + "Born here of parents born here from parents the same, and their " + " parents the same, " + "I, now thirty-seven years old in perfect health begin, " + "Hoping to cease not till death."; + + std::vector<fw_string> v; + + text_tokenizer tok(text,boost::char_separator<char>(" \t\n.,;:!?'\"-")); + for(text_tokenizer::iterator it=tok.begin();it!=tok.end();){ + v.push_back(fw_string(*it++)); + } + + return 0; +}

Modified: sandbox/flyweight/libs/flyweight/test/Jamfile.v2 ============================================================================== --- sandbox/flyweight/libs/flyweight/test/Jamfile.v2 (original) +++ sandbox/flyweight/libs/flyweight/test/Jamfile.v2 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -11,6 +11,7 @@ [ run test_assoc_cont_factory.cpp test_assoc_cont_fact_main.cpp ] [ run test_basic.cpp test_basic_main.cpp ] [ run test_custom_factory.cpp test_custom_factory_main.cpp ] + [ run test_init.cpp test_init_main.cpp ] [ run test_intermod_holder.cpp test_intermod_holder_main.cpp intermod_holder_dll : # command line

Modified: sandbox/flyweight/libs/flyweight/test/test_all_main.cpp ============================================================================== --- sandbox/flyweight/libs/flyweight/test/test_all_main.cpp (original) +++ sandbox/flyweight/libs/flyweight/test/test_all_main.cpp 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -14,6 +14,7 @@ #include "test_basic.hpp" #include "test_custom_factory.hpp" #include "test_intermod_holder.hpp" +#include "test_init.hpp" #include "test_multictor.hpp" #include "test_no_locking.hpp" #include "test_no_tracking.hpp" @@ -25,6 +26,7 @@ test_assoc_container_factory(); test_basic(); test_custom_factory(); + test_init(); #if !defined(BOOST_MSVC)||!(BOOST_MSVC<1300) test_intermodule_holder();

Added: sandbox/flyweight/libs/flyweight/test/test_init.cpp ============================================================================== --- (empty file) +++ sandbox/flyweight/libs/flyweight/test/test_init.cpp 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -0,0 +1,47 @@ +/* Boost.Flyweight test of static data initialization facilities. + * + * Copyright 2006-2007 Joaquín M López Muñoz. + * Distributed under the Boost Software License, Version 1.0. + * (See accompanying file LICENSE_1_0.txt or copy at + * http://www.boost.org/LICENSE_1_0.txt) + * + * See http://www.boost.org/libs/flyweight for library home page. + */ + +#include "test_init.hpp" + +#include <boost/config.hpp> /* keep it first to prevent nasty warns in MSVC */ +#include <boost/detail/lightweight_test.hpp> +#include <boost/flyweight.hpp> + +using namespace boost::flyweights; + +template<bool* pmark,typename Entry,typename Value> +struct marked_hashed_factory_class:hashed_factory_class<Entry,Value> +{ + marked_hashed_factory_class(){*pmark=true;} +}; + +template<bool* pmark> +struct marked_hashed_factory:factory_marker +{ + template<typename Entry,typename Value> + struct apply + { + typedef marked_hashed_factory_class<pmark,Entry,Value> type; + }; +}; + +namespace{ +bool mark1=false; +bool init1=flyweight<int,marked_hashed_factory<&mark1> >::init(); + +bool mark2=false; +flyweight<int,marked_hashed_factory<&mark2> >::initializer init2; +} + +void test_init() +{ + BOOST_TEST(mark1); + BOOST_TEST(mark2); +}

Added: sandbox/flyweight/libs/flyweight/test/test_init.hpp ============================================================================== --- (empty file) +++ sandbox/flyweight/libs/flyweight/test/test_init.hpp 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -0,0 +1,11 @@ +/* Boost.Flyweight test of static data initialization facilities. + * + * Copyright 2006-2007 Joaquín M López Muñoz. + * Distributed under the Boost Software License, Version 1.0. + * (See accompanying file LICENSE_1_0.txt or copy at + * http://www.boost.org/LICENSE_1_0.txt) + * + * See http://www.boost.org/libs/flyweight for library home page. + */ + +void test_init();

Added: sandbox/flyweight/libs/flyweight/test/test_init_main.cpp ============================================================================== --- (empty file) +++ sandbox/flyweight/libs/flyweight/test/test_init_main.cpp 2007-12-17 16:38:56 EST (Mon, 17 Dec 2007) @@ -0,0 +1,18 @@ +/* Boost.Flyweight test of static data initialization facilities. + * + * Copyright 2006-2007 Joaquín M López Muñoz. + * Distributed under the Boost Software License, Version 1.0. + * (See accompanying file LICENSE_1_0.txt or copy at + * http://www.boost.org/LICENSE_1_0.txt) + * + * See http://www.boost.org/libs/flyweight for library home page. + */ + +#include <boost/detail/lightweight_test.hpp> +#include "test_init.hpp" + +int main() +{ + test_init(); + return boost::report_errors(); +}




Next message: eric_at_[hidden]: "[Boost-commit] svn:boost r42135 - in branches/proto/v3/boost/xpressive/proto: . detail"
Previous message: eric_at_[hidden]: "[Boost-commit] svn:boost r42133 - in branches/proto/v3: boost/xpressive/proto boost/xpressive/proto/detail libs/xpressive/proto/test"






Date view
Thread view
Subject view
Author view





Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk