| Home | Libraries | People | FAQ | More

## Function deconstruct

boost::signals2::deconstruct — Create a `shared_ptr` with support for post-constructors and pre-destructors.

## Synopsis

    // In header: <boost/signals2/deconstruct.hpp>

    template<typename T> postconstructor_invoker<T> deconstruct();
    template<typename T, typename A1>
      postconstructor_invoker<T> deconstruct(const A1 & arg1);
    template<typename T, typename A1, typename A2>
      postconstructor_invoker<T> deconstruct(const A1 & arg1, const A2 & arg2);
    template<typename T, typename A1, typename A2, ..., typename AN>
      postconstructor_invoker<T>
      deconstruct(const A1 & arg1, const A2 & arg2, ..., const AN & argN);

## Description

Creates an object and its owning `shared_ptr<T>` (wrapped inside a `postconstructor_invoker`) using only a single allocation, in a manner similar to that of `boost::make_shared()`. In addition, `deconstruct` supports postconstructors and predestructors. The returned `shared_ptr` is wrapped inside a `postconstructor_invoker` in order to provide the user with an opportunity to pass arguments to a postconstructor, while insuring the postconstructor is run before the wrapped `shared_ptr` is accessible.

In order to use `deconstruct` you must define a postconstructor for your class. More specifically, you must define an `adl_postconstruct` function which can be found via argument-dependent lookup. Typically, this means defining an `adl_postconstruct` function in the same namespace as its associated class. See the reference for `postconstructor_invoker` for a specification of what arguments are passed to the `adl_postconstruct` call.

Optionally, you may define a predestructor for your class. This is done by defining an `adl_predestruct` function which may be found by argument-dependent lookup. The deleter of the `shared_ptr` created by `deconstruct` will make an unqualified call to `adl_predestruct` 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 `adl_predestruct`. If no user-defined `adl_predestruct` function is found via argument-dependent lookup, a default function (which does nothing) will be used. After `adl_predestruct` is called, the deleter will delete the object with `checked_delete`.

Any arguments passed to a `deconstruct()` call are forwarded to the matching constructor of the template type `T`. Arguments may also be passed to the class' associated `adl_postconstruct` function by using the `postconstructor_invoker::postconstruct()` methods.

Notes:

If your compiler supports the C++0x features of rvalue references and variadic templates, then `deconstruct` will perform perfect forwarding of arguments to the `T` constructor, using a prototype of:

    template< typename T, typename... Args > postconstructor_invoker< T > deconstruct( Args && ... args );

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 boost::ref.

You may give all the `deconstruct` overloads access to your class' private and protected constructors by declaring deconstruct_access a friend. Using private constructors in conjunction with deconstruct_access can be useful to ensure your objects are only created by `deconstruct`, and thus their postconstructors or predestructors will always be called.

Returns: | A `postconstructor_invoker<T>` owning a newly allocated object of type `T`.