boost_mirror/utility
1
0
Fork 0
mirror of https://github.com/boostorg/utility.git synced 2025-05-09 15:04:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

bad links fixed

Browse Source 
added myself to people


[SVN r25610]
This commit is contained in:
Fernando Cacciola 2004-10-07 16:01:24 +00:00
parent e854726be0
commit 30d46adcb7
1 changed files with 50 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
in_place_factories.html
View File

@ -4,7 +4,7 @@
<HEAD> <HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="stylesheet" TYPE="text/css" HREF="../../../boost.css"> <LINK REL="stylesheet" TYPE="text/css" HREF="../../boost.css">
<TITLE>Header </TITLE> <TITLE>Header </TITLE>
</HEAD> </HEAD>
@ -18,10 +18,10 @@
<blockquote> <blockquote>
<blockquote> <blockquote>
<H2 align="left">Header &lt;<A <H2 align="left">Header &lt;<A
HREF="../../../boost/utility/in_place_factory.hpp">boost/utility/in_place_factory.hpp</A>&gt; </H2> HREF="../../boost/utility/in_place_factory.hpp">boost/utility/in_place_factory.hpp</A>&gt; </H2>
<H2 align="left">Header &lt;<A <H2 align="left">Header &lt;<A
HREF="../../../boost/utility/typed_in_place_factory.hpp">boost/utility/typed_in_place_factory.hpp</A>&gt; </H2> HREF="../../boost/utility/typed_in_place_factory.hpp">boost/utility/typed_in_place_factory.hpp</A>&gt; </H2>
</blockquote> </blockquote>
</blockquote> </blockquote>
@ -45,9 +45,9 @@ HREF="../../../boost/utility/typed_in_place_factory.hpp">boost/utility/typed_in_
<H2><A NAME="mot"></A>Motivation</H2> <H2><A NAME="mot"></A>Motivation</H2>
<p>Suppose we have a class</p> <p>Suppose we have a class</p>
<pre>struct X <pre>struct X
{ {
X ( int, std:::string ) ; X ( int, std:::string ) ;
} ;</pre> } ;</pre>
<p>And a container for it which supports an empty state (that is, which can contain zero objects):</p> <p>And a container for it which supports an empty state (that is, which can contain zero objects):</p>
<pre>struct C <pre>struct C
@ -57,7 +57,7 @@ HREF="../../../boost/utility/typed_in_place_factory.hpp">boost/utility/typed_in_
X* contained_ ; X* contained_ ;
} ;</pre> } ;</pre>
<p>A container designed to support an empty state typically doesn't require the contained type to be DefaultConstructible, <p>A container designed to support an empty state typically doesn't require the contained type to be DefaultConstructible,
but it typically requires it to be CopyConstructible as a mechanism to but it typically requires it to be CopyConstructible as a mechanism to
initialize the object to store:</p> initialize the object to store:</p>
<pre>struct C <pre>struct C
{ {
@ -67,17 +67,17 @@ initialize the object to store:</p>
X* contained_ ; X* contained_ ;
} ;</pre> } ;</pre>
<p>There is a subtle problem with this: since the mechanism used to initialize the stored object is copy construction, <p>There is a subtle problem with this: since the mechanism used to initialize the stored object is copy construction,
there must exist a previously constructed source object to copy from. This there must exist a previously constructed source object to copy from. This
object is likely to be temporary and serve no purpose besides being the source</p> object is likely to be temporary and serve no purpose besides being the source</p>
<pre>void foo() <pre>void foo()
{ {
// Temporary object created. // Temporary object created.
C c( X(123,"hello") ) ; C c( X(123,"hello") ) ;
} }
</pre> </pre>
<p>A solution to this problem is to support direct construction of the contained <p>A solution to this problem is to support direct construction of the contained
object right in the container's storage.<br> object right in the container's storage.<br>
In this shceme, the user supplies the arguments for the X constructor In this shceme, the user supplies the arguments for the X constructor
directly to the container:</p> directly to the container:</p>
<pre>struct C <pre>struct C
{ {
@ -91,7 +91,7 @@ directly to the container:</p>
{ {
// Wrapped object constructed in-place // Wrapped object constructed in-place
// No temporary created. // No temporary created.
C c(123,"hello") ; C c(123,"hello") ;
} }
</pre> </pre>
<p>Clearly, this solution doesn't scale well since the container must duplicate all the constructor overloads from the contained type <p>Clearly, this solution doesn't scale well since the container must duplicate all the constructor overloads from the contained type
@ -99,8 +99,8 @@ directly to the container:</p>
<H2><A NAME="framework"></A>Framework</H2> <H2><A NAME="framework"></A>Framework</H2>
<p> <p>
This library proposes a framework to allow some containers to directly contruct contained objects in-place without requiring This library proposes a framework to allow some containers to directly contruct contained objects in-place without requiring
the entire set of constructor overloads ftom the contained type. It also allows the container to remove the CopyConstuctible the entire set of constructor overloads ftom the contained type. It also allows the container to remove the CopyConstuctible
requirement from the contained type since objects can be directly constructed in-place without need of a copy.<br> requirement from the contained type since objects can be directly constructed in-place without need of a copy.<br>
The only requirement on the container is that it must provide proper storage (that is, correctly aligned and sized). The only requirement on the container is that it must provide proper storage (that is, correctly aligned and sized).
Naturally, the container will typically support uninitialized storage to avoid the in-place construction to override Naturally, the container will typically support uninitialized storage to avoid the in-place construction to override
@ -108,30 +108,30 @@ a fully-constructed object (as this would defeat the purpose of in-place constru
</p> </p>
<p>For this purpose, the framework provides two families of classes collectively called: InPlaceFactories and TypedInPlaceFactories.<br> <p>For this purpose, the framework provides two families of classes collectively called: InPlaceFactories and TypedInPlaceFactories.<br>
Essentially, these classes hold a sequence of actual parameters and a method to contruct an object in place using these parameters. Essentially, these classes hold a sequence of actual parameters and a method to contruct an object in place using these parameters.
Each member of the family differs only in the number (and type) of the parameter list. The first family Each member of the family differs only in the number (and type) of the parameter list. The first family
takes the type of the object to construct directly in method provided for that takes the type of the object to construct directly in method provided for that
purpose, whereas the second family incorporates that type in the factory class purpose, whereas the second family incorporates that type in the factory class
itself..</p> itself..</p>
<p>From the container POV, using the framework amounts to calling the factory's method to contruct the object in place. <p>From the container POV, using the framework amounts to calling the factory's method to contruct the object in place.
From the user POV, it amounts to creating the right factory object to hold the parameters and pass it to the container.<br> From the user POV, it amounts to creating the right factory object to hold the parameters and pass it to the container.<br>
The following simplified example shows the basic idea. A complete example follows the formal specification of the framework:</p> The following simplified example shows the basic idea. A complete example follows the formal specification of the framework:</p>
<pre>struct C <pre>struct C
{ {
C() : contained_(0) {} C() : contained_(0) {}
C ( X const& v ) : contained_ ( new X(v) ) {} C ( X const& v ) : contained_ ( new X(v) ) {}
template&lt;class InPlaceFactory&gt; template&lt;class InPlaceFactory&gt;
C ( InPlaceFactory const& aFactoty ) C ( InPlaceFactory const& aFactoty )
: :
contained_ ( uninitialized_storage() ) contained_ ( uninitialized_storage() )
{ {
aFactory.template apply&lt;X&gt;(contained_); aFactory.template apply&lt;X&gt;(contained_);
} }
~C() { delete contained_ ; } ~C() { delete contained_ ; }
X* uninitialized_storage() { return static_cast&lt;X*&gt;(new char[sizeof(X)]) ; } X* uninitialized_storage() { return static_cast&lt;X*&gt;(new char[sizeof(X)]) ; }
X* contained_ ; X* contained_ ;
} ; } ;
@ -157,13 +157,13 @@ class in_place_factory : public in_place_factory_base
public:</PRE> public:</PRE>
<PRE> in_place_factory ( A0 const& a0 ) : m_a0(a0) {} <PRE> in_place_factory ( A0 const& a0 ) : m_a0(a0) {}
template&lt; class T &gt; template&lt; class T &gt;
void apply ( void* address ) const void apply ( void* address ) const
{ {
new (address) T(m_a0); new (address) T(m_a0);
} }
private:</PRE> private:</PRE>
<PRE> A0 const& m_a0 ; <PRE> A0 const& m_a0 ;
@ -176,7 +176,7 @@ in_place_factory&lt;A0&gt; in_place ( A0 const& a0 )
} }
</PRE> </PRE>
<p>Similarly, the following is the first member of the family of 'typed_in_place_factory' classes, along with its corresponding <p>Similarly, the following is the first member of the family of 'typed_in_place_factory' classes, along with its corresponding
helper template function. The rest of the family varies only in the number and type of template (and constructor) parameters.</p> helper template function. The rest of the family varies only in the number and type of template (and constructor) parameters.</p>
<PRE>namespace boost { <PRE>namespace boost {
@ -188,12 +188,12 @@ class typed_in_place_factory : public typed_in_place_factory_base
public:</PRE> public:</PRE>
<PRE> typed_in_place_factory ( A0 const& a0 ) : m_a0(a0) {} <PRE> typed_in_place_factory ( A0 const& a0 ) : m_a0(a0) {}
void apply ( void* address ) const void apply ( void* address ) const
{ {
new (address) T(m_a0); new (address) T(m_a0);
} }
private:</PRE> private:</PRE>
<PRE> A0 const& m_a0 ; <PRE> A0 const& m_a0 ;
@ -208,11 +208,11 @@ typed_in_place_factory&lt;A0&gt; in_place ( A0 const& a0 )
<PRE>} <PRE>}
</PRE> </PRE>
<p>As you can see, the 'in_place_factory' and 'typed_in_place_factory' template classes varies only in the way they specify <p>As you can see, the 'in_place_factory' and 'typed_in_place_factory' template classes varies only in the way they specify
the target type: in the first family, the type is given as a template argument to the apply member function while in the the target type: in the first family, the type is given as a template argument to the apply member function while in the
second it is given directly as part of the factory class.<br> second it is given directly as part of the factory class.<br>
When the container holds a unique non-polymorphic type (such as the case of Boost.Optional), it knows the exact dynamic-type When the container holds a unique non-polymorphic type (such as the case of Boost.Optional), it knows the exact dynamic-type
of the contained object and can pass it to the apply() method of a (non-typed) factory. of the contained object and can pass it to the apply() method of a (non-typed) factory.
In this case, end users can use an 'in_place_factory' instance which can be constructed without the type of the object to construct.<br> In this case, end users can use an 'in_place_factory' instance which can be constructed without the type of the object to construct.<br>
However, if the container holds heterogeneous or polymorphic objects (such as the case of Boost.Variant), the dynamic-type However, if the container holds heterogeneous or polymorphic objects (such as the case of Boost.Variant), the dynamic-type
of the object to be constructed must be known by the factory itslef. In this case, end users must use a 'typed_in_place_factory' of the object to be constructed must be known by the factory itslef. In this case, end users must use a 'typed_in_place_factory'
@ -222,13 +222,13 @@ instead.</p>
<h2><A NAME="container-usage">Container-side Usage</a></h2> <h2><A NAME="container-usage">Container-side Usage</a></h2>
<p>As shown in the introductory simplified example, the container class must <p>As shown in the introductory simplified example, the container class must
contain methods that accept an instance of contain methods that accept an instance of
these factories and pass the object's storage to the factory's apply method.<br> these factories and pass the object's storage to the factory's apply method.<br>
However, the type of the factory class cannot be completly specified in the container class because that would However, the type of the factory class cannot be completly specified in the container class because that would
defeat the whole purpose of the factories which is to allow the container to accept a variadic argument list defeat the whole purpose of the factories which is to allow the container to accept a variadic argument list
for the constructor of its contained object.<br> for the constructor of its contained object.<br>
The correct function overload must be based on the only distinctive and common The correct function overload must be based on the only distinctive and common
characteristic of all the classes in each family, the base class.<br> characteristic of all the classes in each family, the base class.<br>
Depending on the container class, you can use 'enable_if' to generate the right overload, or use the following Depending on the container class, you can use 'enable_if' to generate the right overload, or use the following
dispatch technique (used in the Boost.Optional class): dispatch technique (used in the Boost.Optional class):
@ -237,15 +237,15 @@ dispatch technique (used in the Boost.Optional class):
{ {
C() : contained_(0) {} C() : contained_(0) {}
C ( X const& v ) : contained_ ( new X(v) ) {} C ( X const& v ) : contained_ ( new X(v) ) {}
template&lt;class Expr&gt template&lt;class Expr&gt
C ( Expr const& expr ) C ( Expr const& expr )
: :
contained_ ( uninitialized_storage() ) contained_ ( uninitialized_storage() )
{ {
construct(expr,&expr) construct(expr,&expr)
} }
~C() { delete contained_ ; } ~C() { delete contained_ ; }
template&lt;class InPlaceFactory&gt; template&lt;class InPlaceFactory&gt;
@ -253,15 +253,15 @@ dispatch technique (used in the Boost.Optional class):
{ {
aFactory.template apply&lt;X&gt;(contained_); aFactory.template apply&lt;X&gt;(contained_);
} }
template&lt;class TypedInPlaceFactory&gt; template&lt;class TypedInPlaceFactory&gt;
void construct ( TypedInPlaceFactory const& aFactory, boost::typed_in_place_factory_base* ) void construct ( TypedInPlaceFactory const& aFactory, boost::typed_in_place_factory_base* )
{ {
aFactory.apply(contained_); aFactory.apply(contained_);
} }
X* uninitialized_storage() { return static_cast&lt;X*&gt;(new char[sizeof(X)]) ; } X* uninitialized_storage() { return static_cast&lt;X*&gt;(new char[sizeof(X)]) ; }
X* contained_ ; X* contained_ ;
} ; } ;
</pre> </pre>
@ -270,7 +270,7 @@ dispatch technique (used in the Boost.Optional class):
<h2><A NAME="user-usage">User-side Usage</a></h2> <h2><A NAME="user-usage">User-side Usage</a></h2>
<p>End users pass to the container an instance of a factory object holding the actual parameters needed to construct the <p>End users pass to the container an instance of a factory object holding the actual parameters needed to construct the
contained object directly within the container. For this, the helper template function 'in_place' is used.<br> contained object directly within the container. For this, the helper template function 'in_place' is used.<br>
The call 'in_place(a0,a1,a2,...,an)' constructs a (non-typed) 'in_place_factory' instance with the given argument list.<br> The call 'in_place(a0,a1,a2,...,an)' constructs a (non-typed) 'in_place_factory' instance with the given argument list.<br>
The call 'in_place&lt;T&gt;(a0,a1,a2,...,an)' constructs a 'typed_in_place_factory' instance with the given argument list for the The call 'in_place&lt;T&gt;(a0,a1,a2,...,an)' constructs a 'typed_in_place_factory' instance with the given argument list for the
@ -283,13 +283,14 @@ type 'T'.</p>
</pre> </pre>
<P>Revised September 17, 2004</P> <P>Revised September 17, 2004</P>
<P>&copy; Copyright boost.org 2004. Permission to copy, use, modify, sell and <p>© Copyright Fernando Luis Cacciola Carballal, 2004</p>
distribute this document is granted provided this copyright notice appears in <p> Use, modification, and distribution are subject to the Boost Software
all copies. This document is provided &quot;as is&quot; without express or implied License, Version 1.0. (See accompanying file <a href="../../LICENSE_1_0.txt">
warranty, and with no claim as to its suitability for any purpose.</P> LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
www.boost.org/LICENSE_1_0.txt</a>)</p>
<P>Developed by <A HREF="mailto:fernando_cacciola@hotmail.com">Fernando Cacciola</A>, <P>Developed by <A HREF="mailto:fernando_cacciola@hotmail.com">Fernando Cacciola</A>,
the latest version of this file can be found at <A the latest version of this file can be found at <A
HREF="http://www.boost.org">www.boost.org</A>, and the boost HREF="http://www.boost.org">www.boost.org</A>, and the boost
<A HREF="http://www.boost.org/more/mailing_lists.htm#main">discussion lists</A></P> <A HREF="http://www.boost.org/more/mailing_lists.htm#main">discussion lists</A></P>
</BODY> </BODY>
</HTML> </HTML>