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.