xdispatch.dox

/**
@defgroup xdispatch libxdispatch

libxdispatch is a C++ API build on top of libdispatch and simplifying the usage by providing
an object-oriented way of leveraging the techniques provided.

@section xd_blocks Use of Blocks

When Apple introduced Grand Central Dispatch it extended its compilers by a new feature they called "Blocks". Basically this
is lambdas (sometimes called closures as well). They allow an easier way to utilize the libdispatch api and are available when using
Clang or the GCC 4.2 that's shipped with Apple's current Developer Tools.

Similiar to the original libdispatch api we provide blocks within the C++ interface as well.
However as we need to support C++ only (and not C at the same time), we have more possibilities to support it.
So instead of being limited to using Clang 2.0+ or Apple's patched GCC version (gcc 4.2 as available on OS X starting with 10.6 'Snow Leopard'),
we can support a broader range of other compilers (e.g. MSVC, GCC 4.5+).

As we wanted to provide this "Blocks support" on Windows (using Visual Studio or MinGW) and Linux (using GCC), we had to come
up with a way to achieve blocks behaviour without actually patching a compiler. Soon after discovering that Blocks are a bit borked when
used with the patched gcc 4.2 in C++, we had a wonderful idea: As the emerging C++0x/C++11 standard would indeed have lambda support, all we
had to do was implement support for lambdas when using the libdispatch API in C++.

The result can be found in lambda_blocks.h - Basically we added lambda detection and a macro to map between apples block syntax and the new
lambda syntax. So basically the following lines do all the same:

@code
xdispatch::global_queue().async(${ printf("Hey Dude"); }); // A macro automatically mapping to [=] or ^ depending on the compiler used
xdispatch::global_queue().async([=]{ printf("Hey Dude"); }); // The [=] is available on platforms supporting C++11 lambdas
xdispatch::global_queue().async(^{ printf("Hey Dude"); }); // The ^ is available on clang / Apple's gcc 4.2 only.
@endcode 

So whenever you use a compiler featuring C++11 or Blocks you can use the block syntax. If not, you can still
use the functor object interface. To become independent from a specific syntax (may it be [=] or ^), simply
use $ - this can be easily redefined.

As the time of writing, the following compilers were tested using our 'cross blocks':
 - Visual Studio 2010
 - GCC 4.5.1+, 4.6.x
 - clang 2.0, 3.0, 3.1
 - gcc 4.2 (latest apple version, although namespaces are quite broken there)
 
All of our tests passed when using those systems.

@remark Please note that when not using one of those compilers you can still use the entire libXDispatch
		 interface, however the blocks support will be disabled.

@remark Also rememeber that some compilers want the C++0x/C++11 features to be explicitly enabled, e.g. GCC has to be called with the flag '-std=gnu++0x'.

@section xd_goodies Goodies when using the libdispatch C API

If for some reason you do not want to or are not allowed to use the C++ interface, we also offer C++ lambda implementations for the 'blocks-API' of the
libdispatch C interface. These convenience functions include
 - dispatch_async
 - dispatch_after
 - dispatch_sync
 - dispatch_apply
 - dispatch_group_async
 - dispatch_group_notify
 - dispatch_source_set_event_handler
 - dispatch_source_set_cancel_handler
 - dispatch_once

See xdispatch/lambda_dispatch.h and the \ref dispatch documentation for details on using these functions.
By including the xdispatch headers (see \ref xd_use), all these functions will be available as well.
Please note that despite only using the C API, you will still need to link against both, the dispatch and the xdispatch libraries.

@section xd_sync Synchronize Keyword

To simplify the threadsafe programming when using C++ we added a new synchronized { } keyword,
loosely inspired by Java and Objective-C. This is a mechanism much easier to use than a standard
mutex. Please see the documentation generated from xdispatch/synchronized.h for details.

@section xd_use Usage

All header files needed for using libxdispatch can be included by typing
@code
#include <xdispatch/dispatch>
@endcode
You will need to link against the xdispatch library.
   
*/