boostorg/functional
1
0
Fork 1
mirror of https://github.com/boostorg/functional.git synced 2025-07-31 13:07:18 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update factory documentation

Browse Source
This commit is contained in:
Glen Fernandes
2019-08-27 21:09:24 -04:00
parent 6520a84e70
commit 1637da95b8
1 changed files with 241 additions and 229 deletions
Download Patch File Download Diff File Expand all files Collapse all files

470
factory/doc/factory.qbk
View File

@ -1,59 +1,67 @@
[library Boost.Functional/Factory [/
[quickbook 1.3] Copyright 2007,2008 Tobias Schwinger
[version 1.0]
[authors [Schwinger, Tobias], [Fernandes, Glen]] Copyright 2019 Glen Joseph Fernandes
[copyright 2007 2008 Tobias Schwinger] (glenjofe@gmail.com)
[copyright 2019 Glen Joseph Fernandes]
[license Distributed under the Boost Software License, Version 1.0.
Distributed under the Boost Software License, Version 1.0. (http://www.boost.org/LICENSE_1_0.txt)
(See accompanying file LICENSE_1_0.txt or copy at
[@http://www.boost.org/LICENSE_1_0.txt])
]
[purpose Function object templates for object creation.]
[category higher-order]
[category generic]
[last-revision $Date: 2008/11/01 21:44:52 $]
] ]
[def __boost_bind__ [@http://www.boost.org/libs/bind/bind.html Boost.Bind]] [library Boost.Functional/Factory
[def __boost__bind__ [@http://www.boost.org/libs/bind/bind.html `boost::bind`]] [quickbook 1.5]
[version 1.0]
[authors [Schwinger, Tobias], [Fernandes, Glen]]
[copyright 2007 2008 Tobias Schwinger]
[copyright 2019 Glen Joseph Fernandes]
[license Distributed under the Boost Software License, Version 1.0.]
[purpose Function object templates for object creation.]
[category higher-order]
[category generic]]
[def __boost__forward_adapter__ [@http://www.boost.org/libs/functional/forward/doc/index.html `boost::forward_adapter`]] [def __boost__bind__
[def __fusion_functional_adapters__ [@http://www.boost.org/libs/fusion/doc/html/functional.html Fusion Functional Adapters]] [@http://www.boost.org/libs/bind/bind.html `boost::bind`]]
[def __boost_function__ [@http://www.boost.org/doc/html/function.html Boost.Function]] [def __boost__forward_adapter__
[def __boost__function__ [@http://www.boost.org/doc/html/function.html `boost::function`]] [@http://www.boost.org/libs/functional/forward/doc/index.html
`boost::forward_adapter`]]
[def __smart_pointer__ [@http://www.boost.org/libs/smart_ptr/index.html Smart Pointer]] [def __boost_function__
[def __smart_pointers__ [@http://www.boost.org/libs/smart_ptr/index.html Smart Pointers]] [@http://www.boost.org/doc/html/function.html Boost.Function]]
[def __boost__shared_ptr__ [@http://www.boost.org/libs/smart_ptr/shared_ptr.htm `boost::shared_ptr`]]
[def __smart_pointer__
[@http://www.boost.org/libs/smart_ptr/index.html Smart Pointer]]
[def __smart_pointers__
[@http://www.boost.org/libs/smart_ptr/index.html Smart Pointers]]
[def __boost__shared_ptr__
[@http://www.boost.org/libs/smart_ptr/shared_ptr.htm `boost::shared_ptr`]]
[def __std__map__ [@https://boost.org/sgi/stl/Map.html `std::map`]]
[def __std__string__ [@https://boost.org/sgi/stl/basic_string.html `std::string`]]
[def __allocator__ [@https://www.boost.org/sgi/stl/Allocators.html Allocator]] [def __allocator__ [@https://www.boost.org/sgi/stl/Allocators.html Allocator]]
[def __std_allocator__ [@https://www.boost.org/sgi/stl/Allocators.html Allocator]]
[def __std_allocators__ [@https://www.boost.org/sgi/stl/Allocators.html Allocators]]
[def __boost__ptr_map__ [@http://www.boost.org/libs/ptr_container/doc/ptr_map.html `boost::ptr_map`]] [def __std_allocators__
[@https://www.boost.org/sgi/stl/Allocators.html Allocators]]
[def __boost__factory__ `boost::factory`] [def __boost__factory__ `boost::factory`]
[def __boost__value_factory__ `boost::value_factory`] [def __boost__value_factory__ `boost::value_factory`]
[def __factory__ `factory`]
[def __value_factory__ `value_factory`] [def __value_factory__ `value_factory`]
[section Brief Description] [section Brief Description]
The template __boost__factory__ lets you encapsulate a `new` expression The template __boost__factory__ lets you encapsulate a `new` expression as a
as a function object, __boost__value_factory__ encapsulates a constructor function object, __boost__value_factory__ encapsulates a constructor invocation
invocation without `new`. without `new`.
__boost__factory__<T*>()(arg1,arg2,arg3) ```
// same as new T(arg1,arg2,arg3) __boost__factory__<T*>()(arg1,arg2,arg3)
// same as new T(arg1,arg2,arg3)
__boost__value_factory__<T>()(arg1,arg2,arg3) __boost__value_factory__<T>()(arg1,arg2,arg3)
// same as T(arg1,arg2,arg3) // same as T(arg1,arg2,arg3)
```
Before C++11 the arguments to the function objects have to be LValues. A Before C++11 the arguments to the function objects have to be LValues. A
factory that also accepts RValues can be composed using the factory that also accepts RValues can be composed using the
@ -68,80 +76,75 @@ In traditional Object Oriented Programming a Factory is an object implementing
an interface of one or more methods that construct objects conforming to known an interface of one or more methods that construct objects conforming to known
interfaces. interfaces.
// assuming a_concrete_class and another_concrete_class are derived ```
// from an_abstract_class // assuming a_concrete_class and another_concrete_class are derived
// from an_abstract_class
class a_factory struct a_factory {
{ virtual an_abstract_class* create() const = 0;
public: virtual ~a_factory() { }
virtual an_abstract_class* create() const = 0; };
virtual ~a_factory() { }
};
class a_concrete_factory : public a_factory struct a_concrete_factory
{ : a_factory {
public: an_abstract_class* create() const {
virtual an_abstract_class* create() const return new a_concrete_class();
{ }
return new a_concrete_class(); };
}
};
class another_concrete_factory : public a_factory struct another_concrete_factory
{ : a_factory {
public: an_abstract_class* create() const {
virtual an_abstract_class* create() const return new another_concrete_class();
{ }
return new another_concrete_class(); };
}
}; // [...]
int main()
{
boost::ptr_map<std::string, a_factory> factories;
// [...] // [...]
int main() factories.insert("a_name",
{ std::unique_ptr<a_factory>(new a_concrete_factory));
__boost__ptr_map__<__std__string__,a_factory> factories; factories.insert("another_name",
std::unique_ptr<a_factory>(new another_concrete_factory));
// [...] // [...]
factories.insert("a_name",std::auto_ptr<a_factory>( std::unique_ptr<an_abstract_class> x(factories.at(some_name).create());
new a_concrete_factory));
factories.insert("another_name",std::auto_ptr<a_factory>(
new another_concrete_factory));
// [...] // [...]
}
```
std::auto_ptr<an_abstract_class> x(factories.at(some_name).create()); This approach has several drawbacks. The most obvious one is that there is lots
of boilerplate code. In other words there is too much code to express a rather
simple intention. We could use templates to get rid of some of it but the
approach remains inflexible:
// [...] * We may want a factory that takes some arguments that are forwarded to the
} constructor,
This approach has several drawbacks. The most obvious one is that there is
lots of boilerplate code. In other words there is too much code to express
a rather simple intention. We could use templates to get rid of some of it
but the approach remains inflexible:
* We may want a factory that takes some arguments that are forwarded to
the constructor,
* we will probably want to use smart pointers, * we will probably want to use smart pointers,
* we may want several member functions to create different kinds of * we may want several member functions to create different kinds of objects,
objects,
* we might not necessarily need a polymorphic base class for the objects, * we might not necessarily need a polymorphic base class for the objects,
* as we will see, we do not need a factory base class at all, * as we will see, we do not need a factory base class at all,
* we might want to just call the constructor - without `new` to create * we might want to just call the constructor - without `new` to create an
an object on the stack, and object on the stack, and
* finally we might want to use customized memory management. * finally we might want to use customized memory management.
Experience has shown that using function objects and generic Boost components Experience has shown that using function objects and generic Boost components
for their composition, Design Patterns that describe callback mechanisms for their composition, Design Patterns that describe callback mechanisms
(typically requiring a high percentage of boilerplate code with pure Object (typically requiring a high percentage of boilerplate code with pure Object
Oriented methodology) become implementable with just few code lines and without Oriented methodology) become implementable with just few code lines and without
extra classes. extra classes.
Factories are callback mechanisms for constructors, so we provide two class Factories are callback mechanisms for constructors, so we provide two class
templates, __boost__value_factory__ and __boost__factory__, that encapsulate templates, __boost__value_factory__ and __boost__factory__, that encapsulate
object construction via direct application of the constructor and the `new` object construction via direct application of the constructor and the `new`
operator, respectively. operator, respectively.
We let the function objects forward their arguments to the construction We let the function objects forward their arguments to the construction
expressions they encapsulate. Over this __boost__factory__ optionally allows expressions they encapsulate. Over this __boost__factory__ optionally allows
@ -149,99 +152,103 @@ the use of smart pointers and __std_allocators__.
Compile-time polymorphism can be used where appropriate, Compile-time polymorphism can be used where appropriate,
template< class T > ```
void do_something() template<class T>
{ void do_something()
// [...] {
T x = T(a,b); // [...]
T x = T(a, b);
// for conceptually similar objects x we neither need virtual // for conceptually similar objects x we neither need virtual
// functions nor a common base class in this context. // functions nor a common base class in this context.
// [...] // [...]
} }
```
Now, to allow inhomogeneous signatures for the constructors of the types passed Now, to allow inhomogeneous signatures for the constructors of the types passed
in for `T` we can use __value_factory__ and __boost__bind__ to normalize between in for `T` we can use __value_factory__ and __boost__bind__ to normalize
them. between them.
template< class ValueFactory > ```
void do_something(ValueFactory make_obj = ValueFactory()) template<class ValueFactory>
{ void do_something(ValueFactory make_obj = ValueFactory())
// [...] {
typename ValueFactory::result_type x = make_obj(a,b); // [...]
typename ValueFactory::result_type x = make_obj(a, b);
// for conceptually similar objects x we neither need virtual // for conceptually similar objects x we neither need virtual
// functions nor a common base class in this context. // functions nor a common base class in this context.
// [...] // [...]
} }
int main() int main()
{ {
// [...] // [...]
do_something(__boost__value_factory__<X>()); do_something(boost::value_factory<X>());
do_something(boost::bind(__boost__value_factory__<Y>(),_1,5,_2)); do_something(boost::bind(boost::value_factory<Y>(), _1, 5, _2));
// construct X(a,b) and Y(a,5,b), respectively. // construct X(a, b) and Y(a, 5, b), respectively.
// [...] // [...]
} }
```
Maybe we want our objects to outlive the function's scope, in this case we Maybe we want our objects to outlive the function's scope, in this case we have
have to use dynamic allocation; to use dynamic allocation;
template< class Factory > ```
whatever do_something(Factory new_obj = Factory()) template<class Factory>
{ whatever do_something(Factory new_obj = Factory())
typename Factory::result_type ptr = new_obj(a,b); {
typename Factory::result_type ptr = new_obj(a, b);
// again, no common base class or virtual functions needed, // again, no common base class or virtual functions needed,
// we could enforce a polymorphic base by writing e.g. // we could enforce a polymorphic base by writing e.g.
// boost::shared_ptr<base> // boost::shared_ptr<base>
// instead of // instead of
// typename Factory::result_type // typename Factory::result_type
// above. // above.
// Note that we are also free to have the type erasure happen // Note that we are also free to have the type erasure happen
// somewhere else (e.g. in the constructor of this function's // somewhere else (e.g. in the constructor of this function's
// result type). // result type).
// [...] // [...]
} }
// [... call do_something like above but with __factory__ instead // [... call do_something like above but with boost::factory instead
// of __value_factory__] // of boost::value_factory]
```
Although we might have created polymorphic objects in the previous example, Although we might have created polymorphic objects in the previous example, we
we have used compile time polymorphism for the factory. If we want to erase have used compile time polymorphism for the factory. If we want to erase the
the type of the factory and thus allow polymorphism at run time, we can type of the factory and thus allow polymorphism at run time, we can use
use __boost_function__ to do so. The first example can be rewritten as __boost_function__ to do so. The first example can be rewritten as follows.
follows.
typedef boost::function< an_abstract_class*() > a_factory; ```
typedef boost::function<an_abstract_class*()> a_factory;
// [...]
int main()
{
std::map<std::string, a_factory> factories;
// [...] // [...]
int main() factories["a_name"] = boost::factory<a_concrete_class*>();
{ factories["another_name"] = boost::factory<another_concrete_class*>();
__std__map__<__std__string__,a_factory> factories;
// [...] // [...]
}
factories["a_name"] = __boost__factory__<a_concrete_class*>(); ```
factories["another_name"] =
__boost__factory__<another_concrete_class*>();
// [...]
}
Of course we can just as easy create factories that take arguments and/or Of course we can just as easy create factories that take arguments and/or
return __smart_pointers__. return __smart_pointers__.
[endsect] [endsect]
[section:reference Reference] [section:reference Reference]
[section value_factory] [section value_factory]
[heading Description] [heading Description]
@ -249,32 +256,36 @@ return __smart_pointers__.
Function object template that invokes the constructor of the type `T`. Function object template that invokes the constructor of the type `T`.
[heading Header] [heading Header]
#include <boost/functional/value_factory.hpp>
```
#include <boost/functional/value_factory.hpp>
```
[heading Synopsis] [heading Synopsis]
namespace boost ```
{ namespace boost {
template< typename T >
class value_factory; template<class T>
} class value_factory;
} // boost
```
[variablelist Notation [variablelist Notation
[[`T`] [an arbitrary type with at least one public constructor]] [[`T`][an arbitrary type with at least one public constructor]]
[[`a0`...`aN`] [argument values to a constructor of `T`]] [[`a0`...`aN`][argument values to a constructor of `T`]]
[[`F`] [the type `value_factory<F>`]] [[`F`][the type `value_factory<F>`]]
[[`f`] [an instance object of `F`]] [[`f`][an instance object of `F`]]]
]
[heading Expression Semantics] [heading Expression Semantics]
[table [table
[[Expression] [Semantics]] [[Expression][Semantics]]
[[`F()`] [creates an object of type `F`.]] [[`F()`][creates an object of type `F`.]]
[[`F(f)`] [creates an object of type `F`.]] [[`F(f)`][creates an object of type `F`.]]
[[`f(a0`...`aN)`] [returns `T(a0`...`aN)`.]] [[`f(a0`...`aN)`][returns `T(a0`...`aN)`.]]
[[`F::result_type`] [is the type `T`.]] [[`F::result_type`][is the type `T`.]]]
]
[heading Limits] [heading Limits]
@ -283,66 +294,68 @@ arbitrary number of arguments is supported.
[endsect] [endsect]
[section factory] [section factory]
[heading Description] [heading Description]
Function object template that dynamically constructs a pointee object for Function object template that dynamically constructs a pointee object for the
the type of pointer given as template argument. Smart pointers may be used type of pointer given as template argument. Smart pointers may be used for the
for the template argument, given that `boost::pointee<Pointer>::type` yields template argument, given that `boost::pointee<Pointer>::type` yields the
the pointee type. pointee type.
If an __allocator__ is given, it is used for memory allocation and the If an __allocator__ is given, it is used for memory allocation and the
placement form of the `new` operator is used to construct the object. placement form of the `new` operator is used to construct the object. A
A function object that calls the destructor and deallocates the memory function object that calls the destructor and deallocates the memory with a
with a copy of the Allocator is used for the second constructor argument copy of the Allocator is used for the second constructor argument of `Pointer`
of `Pointer` (thus it must be a __smart_pointer__ that provides a suitable (thus it must be a __smart_pointer__ that provides a suitable constructor,
constructor, such as __boost__shared_ptr__). such as __boost__shared_ptr__).
If a third template argument is `factory_passes_alloc_to_smart_pointer`, If a third template argument is `factory_passes_alloc_to_smart_pointer`, the
the allocator itself is used for the third constructor argument of `Pointer` allocator itself is used for the third constructor argument of `Pointer`
(__boost__shared_ptr__ then uses the allocator to manage the memory of its (__boost__shared_ptr__ then uses the allocator to manage the memory of its
separately allocated reference counter). separately allocated reference counter).
[heading Header] [heading Header]
#include <boost/functional/factory.hpp>
```
#include <boost/functional/factory.hpp>
```
[heading Synopsis] [heading Synopsis]
namespace boost ```
{ namespace boost {
enum factory_alloc_propagation
{
factory_alloc_for_pointee_and_deleter,
factory_passes_alloc_to_smart_pointer
};
template< typename Pointer, enum factory_alloc_propagation {
class Allocator = void, factory_alloc_for_pointee_and_deleter,
factory_alloc_propagation AllocProp = factory_passes_alloc_to_smart_pointer
factory_alloc_for_pointee_and_deleter > };
class factory;
} template<class Pointer,
class Allocator = void,
factory_alloc_propagation Policy = factory_alloc_for_pointee_and_deleter>
class factory;
} // boost
```
[variablelist Notation [variablelist Notation
[[`T`] [an arbitrary type with at least one public constructor]] [[`T`][an arbitrary type with at least one public constructor]]
[[`P`] [pointer or smart pointer to `T`]] [[`P`][pointer or smart pointer to `T`]]
[[`a0`...`aN`] [argument values to a constructor of `T`]] [[`a0`...`aN`][argument values to a constructor of `T`]]
[[`F`] [the type `factory<P>`]] [[`F`][the type `factory<P>`]]
[[`f`] [an instance object of `F`]] [[`f`][an instance object of `F`]]]
]
[heading Expression Semantics] [heading Expression Semantics]
[table [table
[[Expression] [Semantics]] [[Expression][Semantics]]
[[`F()`] [creates an object of type `F`.]] [[`F()`][creates an object of type `F`.]]
[[`F(f)`] [creates an object of type `F`.]] [[`F(f)`][creates an object of type `F`.]]
[[`f(a0`...`aN)`] [dynamically creates an object of type `T` using [[`f(a0`...`aN)`]
`a0`...`aN` as arguments for the constructor invocation.]] [dynamically creates an object of type `T` using `a0`...`aN` as arguments for
[[`F::result_type`] [is the type `P` with top-level cv-qualifiers removed.]] the constructor invocation.]]
] [[`F::result_type`][is the type `P` with top-level cv-qualifiers removed.]]]
[heading Limits] [heading Limits]
@ -376,18 +389,20 @@ The following features have been removed:
[heading Boost 1.58.0] [heading Boost 1.58.0]
In order to remove the dependency on Boost.Optional, the default parameter In order to remove the dependency on Boost.Optional, the default parameter for
for allocators has been changed from `boost::none_t` to `void`. allocators has been changed from `boost::none_t` to `void`. If you have code
If you have code that has stopped working because it uses `boost::none_t`, that has stopped working because it uses `boost::none_t`, a quick fix is to
a quick fix is to define `BOOST_FUNCTIONAL_FACTORY_SUPPORT_NONE_T`, which will define `BOOST_FUNCTIONAL_FACTORY_SUPPORT_NONE_T`, which will restore support,
restore support, but this will be removed in a future release. but this will be removed in a future release. It should be be relatively easy
It should be be relatively easy to fix this properly. to fix this properly.
[endsect] [endsect]
[section Acknowledgements] [section Acknowledgements]
Eric Niebler requested a function to invoke a type's constructor (with the Tobias Schwinger for creating this library.
Eric Niebler requested a function to invoke a type's constructor (with the
arguments supplied as a Tuple) as a Fusion feature. These Factory utilities are arguments supplied as a Tuple) as a Fusion feature. These Factory utilities are
a factored-out generalization of this idea. a factored-out generalization of this idea.
@ -396,25 +411,22 @@ useful hints for the implementation.
Joel de Guzman's documentation style was copied from Fusion. Joel de Guzman's documentation style was copied from Fusion.
Further, I want to thank Peter Dimov for sharing his insights on language Peter Dimov for sharing his insights on language details and their evolution.
details and their evolution.
[endsect] [endsect]
[section References] [section References]
# [@http://en.wikipedia.org/wiki/Design_Patterns Design Patterns], # [@http://en.wikipedia.org/wiki/Design_Patterns Design Patterns],
Gamma et al. - Addison Wesley Publishing, 1995 Gamma et al. - Addison Wesley Publishing, 1995
# [@https://boost.org/sgi/stl/ Standard Template Library Programmer's Guide], # [@https://boost.org/sgi/stl/ Standard Template Library Programmer's Guide],
Hewlett-Packard Company, 1994 Hewlett-Packard Company, 1994
# [@http://www.boost.org/libs/bind/bind.html Boost.Bind], # [@http://www.boost.org/libs/bind/bind.html Boost.Bind],
Peter Dimov, 2001-2005 Peter Dimov, 2001-2005
# [@http://www.boost.org/doc/html/function.html Boost.Function], # [@http://www.boost.org/doc/html/function.html Boost.Function],
Douglas Gregor, 2001-2004 Douglas Gregor, 2001-2004
[endsect] [endsect]