220 lines
11 KiB
XML
220 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
|
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
<!--
|
|
Copyright Frank Mori Hess 2009
|
|
|
|
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)
|
|
-->
|
|
<header name="boost/signals2/deconstruct.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
|
|
<using-namespace name="boost::signals2"/>
|
|
<using-namespace name="boost"/>
|
|
<namespace name="boost">
|
|
<namespace name="signals2">
|
|
<overloaded-function name="deconstruct">
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="T"/>
|
|
</template>
|
|
<type><classname>postconstructor_invoker</classname><T></type>
|
|
</signature>
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="T"/>
|
|
<template-type-parameter name="A1"/>
|
|
</template>
|
|
<type><classname>postconstructor_invoker</classname><T></type>
|
|
<parameter name="arg1"><paramtype>const A1 &</paramtype></parameter>
|
|
</signature>
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="T"/>
|
|
<template-type-parameter name="A1"/>
|
|
<template-type-parameter name="A2"/>
|
|
</template>
|
|
<type><classname>postconstructor_invoker</classname><T></type>
|
|
<parameter name="arg1"><paramtype>const A1 &</paramtype></parameter>
|
|
<parameter name="arg2"><paramtype>const A2 &</paramtype></parameter>
|
|
</signature>
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="T"/>
|
|
<template-type-parameter name="A1"/>
|
|
<template-type-parameter name="A2, ..."/>
|
|
<template-type-parameter name="AN"/>
|
|
</template>
|
|
<type><classname>postconstructor_invoker</classname><T></type>
|
|
<parameter name="arg1"><paramtype>const A1 &</paramtype></parameter>
|
|
<parameter name="arg2"><paramtype>const A2 &</paramtype></parameter>
|
|
<parameter name=""><paramtype>...</paramtype></parameter>
|
|
<parameter name="argN"><paramtype>const AN &</paramtype></parameter>
|
|
</signature>
|
|
|
|
<purpose>Create a <code>shared_ptr</code> with support for post-constructors and pre-destructors.</purpose>
|
|
|
|
<description>
|
|
<para>Creates an object and its owning <code>shared_ptr<T></code>
|
|
(wrapped inside a <classname>postconstructor_invoker</classname>)
|
|
using only a single allocation,
|
|
in a manner similar
|
|
to that of <functionname>boost::make_shared()</functionname>. In addition, <code>deconstruct</code>
|
|
supports postconstructors and predestructors. The returned
|
|
<classname>shared_ptr</classname> is wrapped inside a <classname>postconstructor_invoker</classname>
|
|
in order to provide the user with an opportunity to pass arguments to a postconstructor,
|
|
while insuring the postconstructor is run before the wrapped
|
|
<classname>shared_ptr</classname> is accessible.
|
|
</para>
|
|
<para>
|
|
In order to use <code>deconstruct</code> you must define a postconstructor for your class.
|
|
More specifically, you must define
|
|
an <code>adl_postconstruct</code> function which can be found via argument-dependent
|
|
lookup. Typically, this means defining an <code>adl_postconstruct</code> function
|
|
in the same namespace as its associated class. See the reference for
|
|
<classname>postconstructor_invoker</classname>
|
|
for a specification of what arguments are passed to the <code>adl_postconstruct</code>
|
|
call.
|
|
</para>
|
|
<para>
|
|
Optionally, you may define a predestructor for your class. This is done by
|
|
defining an <code>adl_predestruct</code> function which may be found
|
|
by argument-dependent lookup. The deleter of the <classname>shared_ptr</classname>
|
|
created by <code>deconstruct</code> will make an unqualified call to
|
|
<code>adl_predestruct</code> with a single
|
|
argument: a pointer to the object which is about to be deleted.
|
|
As a convenience, the pointer will always be cast to point to a non-const type
|
|
before being passed to <code>adl_predestruct</code>.
|
|
If no user-defined <code>adl_predestruct</code> function is found via
|
|
argument-dependent lookup, a default function (which does nothing) will
|
|
be used. After <code>adl_predestruct</code> is called, the deleter
|
|
will delete the object with
|
|
<functionname>checked_delete</functionname>.
|
|
</para>
|
|
<para>
|
|
Any arguments passed to a
|
|
<code>deconstruct()</code> call are forwarded to the matching constructor of the
|
|
template type
|
|
<code>T</code>. Arguments may also be passed to the class' associated
|
|
<code>adl_postconstruct</code> function by using the
|
|
<methodname>postconstructor_invoker::postconstruct()</methodname> methods.
|
|
</para>
|
|
</description>
|
|
<notes>
|
|
<para>If your compiler supports the C++11 features of rvalue references
|
|
and variadic templates, then <code>deconstruct</code> will perform perfect
|
|
forwarding of arguments to the <code>T</code> constructor, using
|
|
a prototype of:
|
|
</para>
|
|
<programlisting>template< typename T, typename... Args > postconstructor_invoker< T > deconstruct( Args && ... args );</programlisting>
|
|
<para>Otherwise, argument forwarding is performed via const references, as specified in
|
|
the synopsis. In order to pass non-const references to a constructor, you will need
|
|
to wrap them in reference wrappers using <functionname>boost::ref</functionname>.
|
|
</para>
|
|
<para>You may give all the <code>deconstruct</code> overloads access to your class'
|
|
private and protected constructors by
|
|
declaring <classname>deconstruct_access</classname> a friend. Using private
|
|
constructors in conjunction with <classname>deconstruct_access</classname>
|
|
can be useful to
|
|
ensure your objects are only created by <code>deconstruct</code>, and thus
|
|
their postconstructors or predestructors will always be called.
|
|
</para>
|
|
</notes>
|
|
<returns><para>A <code>postconstructor_invoker<T></code> owning a newly allocated object of
|
|
type <code>T</code>.</para>
|
|
</returns>
|
|
</overloaded-function>
|
|
<class name="deconstruct_access">
|
|
<purpose>Gives <functionname>deconstruct</functionname> access to private/protected constructors.</purpose>
|
|
<description>
|
|
<para>
|
|
Declaring <code>deconstruct_access</code> a friend to your class will give the
|
|
<functionname>deconstruct</functionname> factory function access to your class' private and
|
|
protected constructors. Using private
|
|
constructors in conjunction with <code>deconstruct_access</code>
|
|
can be useful to
|
|
ensure <classname>postconstructible</classname> or <classname>predestructible</classname>
|
|
objects are always created
|
|
properly using <code>deconstruct</code>.
|
|
</para>
|
|
</description>
|
|
</class>
|
|
<class name="postconstructor_invoker">
|
|
<method-group name="public methods">
|
|
<method name="conversion-operator">
|
|
<type>const shared_ptr<T> &</type>
|
|
<description>
|
|
<para>
|
|
The conversion operator has the same effect as explicitly calling
|
|
the <methodname>postconstruct</methodname> method with no arguments.
|
|
</para>
|
|
</description>
|
|
</method>
|
|
<overloaded-method name="postconstruct" cv="const">
|
|
<signature>
|
|
<type>const shared_ptr<T> &</type>
|
|
</signature>
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="A1"/>
|
|
</template>
|
|
<type>const shared_ptr<T> &</type>
|
|
<parameter name="a1"><paramtype>A1</paramtype></parameter>
|
|
</signature>
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="A1"/>
|
|
<template-type-parameter name="A2"/>
|
|
</template>
|
|
<type>const shared_ptr<T> &</type>
|
|
<parameter name="a1"><paramtype>A1</paramtype></parameter>
|
|
<parameter name="a2"><paramtype>A1</paramtype></parameter>
|
|
</signature>
|
|
<signature>
|
|
<template>
|
|
<template-type-parameter name="A1"/>
|
|
<template-type-parameter name="A2, ..."/>
|
|
<template-type-parameter name="AN"/>
|
|
</template>
|
|
<type>const shared_ptr<T> &</type>
|
|
<parameter name="a1"><paramtype>A1</paramtype></parameter>
|
|
<parameter name="a2"><paramtype>A1</paramtype></parameter>
|
|
<parameter name=""><paramtype>...</paramtype></parameter>
|
|
<parameter name="aN"><paramtype>A1</paramtype></parameter>
|
|
</signature>
|
|
<description>
|
|
<para>
|
|
The <code>postconstruct</code> methods make an unqualified call to
|
|
<code>adl_postconstruct()</code> and then return the <classname>shared_ptr</classname>
|
|
which was wrapped inside the <code>postconstructor_invoker</code>
|
|
object by <functionname>deconstruct()</functionname>.
|
|
The first two arguments passed to the
|
|
<code>adl_postconstruct()</code> call are always the <classname>shared_ptr</classname>
|
|
owning the object created by <functionname>deconstruct()</functionname>,
|
|
followed by a ordinary pointer to the same object. As a convenience,
|
|
the ordinary pointer
|
|
will always be cast to point to a non-const type before being passed
|
|
to <code>adl_postconstruct</code>. The remaining arguments passed to
|
|
<code>adl_postconstruct</code> are whatever arguments the user may have
|
|
passed to the <code>postconstruct</code>
|
|
method.
|
|
</para>
|
|
</description>
|
|
</overloaded-method>
|
|
</method-group>
|
|
<purpose>Pass arguments to and run postconstructors for objects created with <functionname>deconstruct()</functionname>.</purpose>
|
|
<description>
|
|
<para>
|
|
Objects of type <code>postconstructor_invoker</code> are returned by calls to the
|
|
<functionname>deconstruct()</functionname> factory function. These objects are intended
|
|
to either be immediately assigned to a <classname>shared_ptr</classname> (in which case the
|
|
class' conversion operator will perform the conversion by calling the
|
|
<methodname>postconstruct</methodname> with no arguments), or to be converted
|
|
to <classname>shared_ptr</classname> explicitly by the user calling one of
|
|
the <methodname>postconstruct</methodname> methods.
|
|
</para>
|
|
</description>
|
|
</class>
|
|
</namespace>
|
|
</namespace>
|
|
</header>
|