/**
\defgroup fcpptsmartptr fcppt.smart_pointers
\ingroup fcpptmain
\brief unique_ptr, shared_ptr and weak_ptr without default constructors.

<table id="toc">
<tr>
<td>

<ul>
	<li>\ref smartptr_introduction</li>
	<li>\ref smartptr_types</li>
	<li>\ref smartptr_shared_ptr</li>
	<ul>
		<li>\ref smartptr_shared_ptr_make_shared</li>
		<li>\ref smartptr_shared_ptr_weak_ptr</li>
		<li>\ref smartptr_shared_ptr_casts</li>
	</ul>
	<li>\ref smartptr_unique_ptr</li>
	<ul>
		<li>\ref smartptr_unique_ptr_usage</li>
		<li>\ref smartptr_unique_ptr_move</li>
		<li>\ref smartptr_unique_ptr_convert</li>
		<li>\ref smartptr_unique_ptr_const</li>
		<li>\ref smartptr_unique_ptr_pimpl</li>
	</ul>
	<li>\ref smartptr_deleter</li>
	<ul>
		<li>\ref smartptr_deleter_predef</li>
		<li>\ref smartptr_deleter_example</li>
	</ul>
	<li>\ref smartptr_headers</li>
</ul>

</td>
</tr>
</table>

\section smartptr_introduction Introduction

A smart pointer is a class that takes ownership over a pointer, freeing the
object pointed to when the smart pointer is destroyed. Such a smart pointer
resides on the stack, so freeing is done automatically.

fcppt provides all smart pointers that are also in C++11 with the following
changes:
<ul>
<li>fcppt's smart pointers do not have a default constructor and are not meant
to be used as null pointers. Instead, \ref fcppt.optional should be used.</li>
<li>Deleters are template parameters for all smart pointers. This is a
trade-off and removes some of the dynamic behaviour, switching it for a
statically type-safe one.</li>
<li>Deleters do not use template parameters of their own. If a smart pointer is
convertible to another smart pointer solely depends on the pointer type.</li>
</ul>

\section smartptr_types Smart pointer types

fcppt provides three smart pointer classes, each with their own trade-offs.

<table>
<tr>
<th>Class name</th>
<th>Description</th>
</tr>

<tr>
<td>#fcppt::unique_ptr</td>

<td>A move-only smart pointer that is the unique owner of an object. This
should be the default choice of smart pointer.</td>

</tr>

<tr>
<td>#fcppt::shared_ptr</td>

<td>Manages objects using a shared count. Every shared ptr pointing to the same
object increases the shared count by one. The object will only be destroyed
when all shared ptrs have been destroyed.</td>

</tr>

<tr>
<td>#fcppt::weak_ptr</td>

<td>A weak reference to an object managed by shared ptrs. This smart pointer
doesn't contribute to the shared count and can be used to observe if shared
ptrs are still alive.</td>

</tr>
</table>

\section smartptr_shared_ptr Shared Pointers

Multiple #fcppt::shared_ptr that point to the same object share
ownership by internally managing a shared count that counts how many shared
ptrs are left. This shared count will be increased whenever a shared ptr is
copied and decreased when one is destroyed.

For most use cases, unique ptrs should be preferred over shared ptrs.

The general traits of a shared ptr are as follows:

<ul>

<li>Copying, destroying and assigning of shared ptrs is thread-safe. This
usually means that these atomic operations are involved, making the operations
a lot less cheap than they might seem.</li>

<li>Although the shared ptr gets its deleter as a template parameter, it does
type erasure on it. This implies that the owned object does not have to be
complete unless the shared ptr is constructed or dereferenced.</li>

<li>Because not only the shared count but also the owned object must be
dynamically allocated, it is possible to put them both into the same memory
block if the deleter is the default one that uses <code>delete</code>. This is
done by #fcppt::make_shared_ptr.</li>

<li>An #fcppt::weak_ptr can be used to keep track of the shared
ptrs to one object without contributing to the shared count. This way it is
possible to observe if shared ptrs are still alive.</li>

<li>Casting shared pointers must be done through special functions, so that the
shared count between them is preserved.</li>

</ul>

Here is a simple example using shared pointers.

\snippet shared_ptr.cpp shared_ptr_example

\subsection smartptr_shared_ptr_make_shared Using make_shared

#fcppt::make_shared_ptr can be used to place an object allocated
via new into the same memory block as the shared count managed by the shared
ptrs. Another reason to use this function is to avoid memory leaks, that can
happen due to C++'s unspecified order of evaluation, if you are not careful.

Here is an example of how not using #fcppt::make_shared_ptr can
lead to a memory leak.

\snippet shared_ptr.cpp shared_ptr_make_shared_wrong

Using #fcppt::make_shared_ptr eliminates this problem and also
makes the dynamic memory management of the shared ptrs more efficient.

\snippet shared_ptr.cpp shared_ptr_make_shared_right

\subsection smartptr_shared_ptr_weak_ptr Weak Pointers

A weak pointer can be used to keep track of the shared ptrs to one object
without contributing to the shared count. We can then observe if a shared ptr
is still alive. This can also be used to break cycles.

A weak ptr can be used as follows:

\snippet weak_ptr.cpp weak_ptr

\subsection smartptr_shared_ptr_casts Casting Shared Pointers

When casting shared ptrs, using <code>static_cast</code>,
<code>dynamic_cast</code> or <code>const_cast</code> directly will not work,
because the shared count will not be preserved. Instead, we have to use one of
the special functions #fcppt::static_pointer_cast, #fcppt::dynamic_pointer_cast or #fcppt::const_pointer_cast.

Here is an example:

\snippet shared_ptr.cpp shared_ptr_cast

\section smartptr_unique_ptr Unique Pointers

In contrast to a shared ptr, a unique ptr always is the sole owner of an
object.

The general traits of a unique ptr are as follows:

<ul>

<li>Unique ptrs cannot be copied or assigned. Instead, they must be
<em>moved</em>, which takes the ownership away from the original owner. This
also means that the moved-from object will become the null pointer, so it
should not be dereferenced.</li>

<li>Unique ptrs don't use type erasure for their deleter. This means that when
constructing, copying, assigning, destroying or dereferencing unique ptrs, the
type of the pointed to object must usually be complete (this depends on the
deleter used).</li>

<li>#fcppt::make_unique_ptr should be used to construct
unique ptrs. It is similar to #fcppt::make_shared_ptr in the sense
that it helps to avoid memory leaks, but it is not more efficient than normal
construction of unique ptrs, because there is no shared count to keep track
of.</li>

</ul>

\subsection smartptr_unique_ptr_usage Using Unique Pointers

The first thing to note is that unique ptrs are an excellent candidate for
factory functions. They don't impose overly strict ownership requirements like
shared ptr does. However, unique ptrs can be converted into shared ptrs as
desired. The following example shows how such a factory can be created.

\snippet unique_ptr.cpp unique_ptr_factory

The return of <code>make_unique_ptr</code> doesn't require a move,
because it returns an rvalue.

The factory can be used as follows:

\snippet unique_ptr.cpp unique_ptr_factory_use

Again, there is no move required because the factory also returns an rvalue.

\subsection smartptr_unique_ptr_move Moving Unique Pointers

The next example shows when a move is required. This is generally true when an
lvalue is involved (which means a named object here). The reason for this is to
ensure that a unique ptr doesn't accidentally get its object disowned.

\snippet unique_ptr.cpp unique_ptr_move

Consider the following example where an implicit move would be very dangerous:

\snippet unique_ptr.cpp unique_ptr_move_dangerous

\subsection smartptr_unique_ptr_convert Converting Unique Pointers

Unique pointers are not implicitly convertible to any other unique pointers.
To convert a unique pointer to a unique pointer to base, use #fcppt::unique_ptr_to_base.

\snippet unique_ptr.cpp unique_ptr_to_base

Similarly, #fcppt::unique_ptr_to_const must be used to obtain a
unique pointer to a const object.

\snippet unique_ptr.cpp unique_ptr_to_const

\subsection smartptr_unique_ptr_const Const Unique Pointers

fcppt used to provide a scoped_ptr class similar to
<code>boost::scoped_ptr</code> that additionally took a deleter. This class
has been removed in favor of const unique ptrs.

\snippet unique_ptr.cpp unique_ptr_const

A unique ptr that has been declared const cannot be copied nor moved.
Additionally, it can also not be swapped.

\subsection smartptr_unique_ptr_pimpl Unique Pointers and Pimpl

A unique ptr can also be used to implement the pimpl idiom. When a unique ptr
object is defined, the pointed to object doesn't need to be complete. It only
has to be complete when the destructor of the unique ptr is instantiated.
Therefore, an implementation can be hidden by using unique ptrs as shown
in the following example:

\snippet unique_ptr.cpp unique_ptr_pimpl_header

Because <code>foo</code> has an explicitly declared destructor, the destruction
of the implementation can be hidden in a source file.

\snippet unique_ptr.cpp unique_ptr_pimpl_cpp

\section smartptr_deleter Custom Deleters

As previously mentioned, fcppt's smart pointers all take the deleter as a
template parameter in order to ensure maximum type safety. Such a deleter must
have the following properties:

For some smart pointer over type <code>Type</code> the deleter must be callable
with an expression of type <code>Type *</code>. The deleter must ensure to
destroy the object if it is not a null pointer.

\subsection smartptr_deleter_predef fcppt's Deleters

fcppt predefines several deleters:

For some invented variable name <code>ptr</code> of type <code>Type *</code>
their semantics are as follows:

<table>
<tr>
<td>
#fcppt::default_deleter
</td>
<td>
<code>delete ptr;</code>
</td>
</tr>
<tr>
<td>
#fcppt::c_deleter
</td>
<td>
<code>std::free(ptr);</code>
</td>
</tr>
<tr>
<td>
#fcppt::com_deleter
</td>
<td>
<code>if(ptr) ptr->Release();</code>
</td>
</tr>
</table>

\subsection smartptr_deleter_example Deleter example

The following example shows how fcppt::c_deleter can be used to free memory
allocated via <code>std::malloc</code>

\snippet smart_ptr_deleter.cpp c_deleter

\section smartptr_headers Header files

<table>
<tr>
<th>Header file</th>
<th>Description</th>
</tr>
<tr>
<td><code>c_deleter.hpp</code></td>
<td>Contains #fcppt::c_deleter.</td>
</tr>
<tr>
<td><code>com_deleter.hpp</code></td>
<td>Contains #fcppt::com_deleter.</td>
</tr>
<tr>
<td><code>const_pointer_cast.hpp</code></td>
<td>Contains #fcppt::const_pointer_cast.</td>
</tr>
<tr>
<td><code>default_deleter.hpp</code></td>
<td>Contains #fcppt::default_deleter.</td>
</tr>
<tr>
<td><code>dynamic_pointer_cast.hpp</code></td>
<td>Contains #fcppt::dynamic_pointer_cast.</td>
</tr>
<tr>
<td><code>make_shared_ptr.hpp</code></td>
<td>Contains #fcppt::make_shared_ptr.</td>
</tr>
<tr>
<td><code>make_unique_ptr.hpp</code></td>
<td>Contains #fcppt::make_unique_ptr.</td>
</tr>
<tr>
<td><code>shared_ptr_fwd.hpp</code></td>
<td>Contains #fcppt::shared_ptr's declaration.</td>
</tr>
<tr>
<td><code>shared_ptr_decl.hpp</code></td>
<td>Contains #fcppt::shared_ptr's definition.</td>
</tr>
<tr>
<td><code>shared_ptr_impl.hpp</code></td>
<td>Contains the definition of #fcppt::shared_ptr's member functions.</td>
</tr>
<tr>
<td><code>shared_ptr.hpp</code></td>
<td>The same as <code>shared_ptr_impl.hpp</code></td>
</tr>
<tr>
<td><code>static_pointer_cast.hpp</code></td>
<td>Contains fcppt::static_pointer_cast</td>
</tr>
<tr>
<td><code>unique_ptr_fwd.hpp</code></td>
<td>Contains #fcppt::unique_ptr's declaration.</td>
</tr>
<tr>
<td><code>unique_ptr_decl.hpp</code></td>
<td>Contains #fcppt::unique_ptr's definition.</td>
</tr>
<tr>
<td><code>unique_ptr_impl.hpp</code></td>
<td>Contains the definition of #fcppt::unique_ptr's member functions.</td>
</tr>
<tr>
<td><code>unique_ptr.hpp</code></td>
<td>The same as <code>unique_ptr_impl.hpp</code></td>
</tr>
<tr>
<td><code>unique_ptr_to_base.hpp</code></td>
<td>Contains #fcppt::unique_ptr_to_base.</td>
</tr>
<tr>
<td><code>unique_ptr_to_const.hpp</code></td>
<td>Contains #fcppt::unique_ptr_to_const.</td>
</tr>
<tr>
<td><code>weak_ptr_fwd.hpp</code></td>
<td>Contains fcppt::weak_ptr's declaration.</td>
</tr>
<tr>
<td><code>weak_ptr_decl.hpp</code></td>
<td>Contains fcppt::weak_ptr's definition.</td>
</tr>
<tr>
<td><code>weak_ptr_impl.hpp</code></td>
<td>Contains the definition of fcppt::weak_ptr's member functions.</td>
</tr>
<tr>
<td><code>weak_ptr.hpp</code></td>
<td>The same as <code>weak_ptr_impl.hpp</code></td>
</tr>
</table>
*/
