/**
\defgroup fcpptsignal fcppt.signal
\ingroup fcpptmain
\brief An implementation of a managed signals and slots system (replacement for boost's signals).

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

<ul>
	<li>\ref signal_introduction</li>
	<li>\ref signal_basic_usage</li>
	<li>\ref signal_signals_with_return_values</li>
	<li>\ref signal_disconnect_callbacks</li>
	<li>\ref signal_benchmarks</li>
</ul>

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

\section signal_introduction Introduction

\ref fcppt.signal is a library similar to <code>boost.signals2</code>.
It was created when <code>boost.signals</code> (version 1) was the only
signals library available in boost, which was really slow.
See the old benchmark in \ref signal_benchmarks.
One of the major differences between \ref fcppt.signal and <code>boost.signals2</code>
is that <code>boost.signals2</code> is thread-safe, while \ref fcppt.signal is not,
which makes up for some of the speed difference.

\section signal_basic_usage Basic usage

Here is a simple, motivating example:

\snippet "signal/simple.cpp" signal_simple

A signal is of type #fcppt::signal::object.
This type has a template parameter which contains the signal's function type.
Note that signals may have a return type; see below for more on that.

To attach a callback function to the signal, you have to call the
<code>fcppt::signal::object::connect</code> member function. Arbitrarily many attached
functions are allowed. The <code>connect</code> function returns an #fcppt::signal::auto_connection,
which is a unique pointer to a connection.
The reason behind this is that connections may keep additional information that is
important when they are destroyed (see \ref signal_disconnect_callbacks).
The callback function is disconnected from the signal when the connection object dies.

\section signal_signals_with_return_values Signals with return values

If a signal has a return value other than <code>void</code>, you cannot use
#fcppt::signal::object's default constructor. Instead, there is a constructor
that takes a function of type
\code
result_type(result_type,result_type)
\endcode
where <code>result_type</code> is the return type of the signal's function type. This function
is used to combine the results of the different callbacks that are connected to the signal.
The initial value of this operation is passed when the signal itself is called.

Here is an example which should clarify how combiners are used:

\snippet "signal/combine.cpp" signal_combine

Note that there are setters for both the initial value and the combiner.

\section signal_disconnect_callbacks Disconnect callbacks

One unique feature of #fcppt::signal::object is the ability to receive a
callback from the signal when a connection dies. To demonstrate how this works,
let's say you want to associate a name with a signal. Users can then attach to
such a named signal (think about a Quake-style console where you can register
new console commands). However, when the last connection to a named signal
dies, the signal should die with it. To do that, we define:

\snippet signal/unregister.cpp global_map

To receive disconnect "events", we use #fcppt::signal::object's second
template parameter and set it to #fcppt::signal::unregister::base. Using this
base class, we have the empty method at our disposal to check if there are
connections attached to the signal.

To register to a named signal, we define the following function:

\snippet signal/unregister.cpp register

Note that the remove callbacks' signature is just <code>void()</code>. Our main
might look like this:

\snippet signal/unregister.cpp main

\section signal_benchmarks Benchmarks

Out benchmark is as follows:

<ul>
	<li>
		Define a global function which outputs something on the console.
	</li>
	<li>
		Create a signal, attach the global function 1.000.000 times,
		store the connections inside a <code>vector</code>.
	</li>
	<li>
		Call the signal.
	</li>
</ul>

The results were as follows:

<table>
	<tr>
		<th>
			Signals-Implementation
		</th>
		<th>
			gcc-4.6 (<code>-O3</code>)
		</th>
		<th>
			clang-3.0 (<code>-O3</code>)
		</th>
		<th>
			icc-12.1.0 (<code>-O3</code>)
		</th>
	</tr>
	<tr>
		<td>boost.signals</td>
		<td>1.426s</td>
		<td>1.444s</td>
		<td>1.679s</td>
	</tr>
	<tr>
		<td>boost.signals2</td>
		<td>0.871s</td>
		<td>1.644s</td>
		<td>1.728s</td>
	</tr>
	<tr>
		<td>libsigc++</td>
		<td>0.614s</td>
		<td>0.615s</td>
		<td>0.647s</td>
	</tr>
	<tr>
		<td>fcppt.signal</td>
		<td>0.526s</td>
		<td>0.505s</td>
		<td>0.539s</td>
	</tr>
</table>

Or graphically:

\image html signal_benchmark.svg "Benchmark results"
*/

namespace fcppt
{
/**
\brief An implementation of a managed signals and slots system (replacement for boost's signals).
*/
namespace signal
{
/**
\brief Contains classes and functions related to unregistration callbacks
*/
namespace unregister
{
}
}
}
