Building and installing

Building Async++

Building Async++ requires CMake 3.1+ and a C++11 compiler. Currently supported compilers are:

• GCC 4.7+ (GCC 4.8+ is required for MinGW)
• Clang 3.2+
• Intel C++ compiler 15+
• MSVC 2013+

Building the library is done using CMake. You can run the CMake GUI to configure the library or use the command line:

mkdir build
cd build
ccmake ..
make

The following options are available in CMake:

Option	Description
BUILD_SHARED_LIBS	Whether to build Async++ as a shared library or a static library. When using a static library, you should define LIBASYNC_STATIC in files that include async++.h.
CMAKE_BUILD_TYPE	Type of build (Debug, Release, RelWithDebInfo, MinSizeRel)
USE_CXX_EXCEPTIONS	Whether to use C++ exceptions. When exceptions are disabled, any operation that would normally cause an exception to be thrown will instead call std::abort. While this does not affect the library ABI, you also need to define LIBASYNC_NO_EXCEPTIONS in files that include async++.h to ensure that inline functions defined in headers also abort instead of throwing exceptions.

Using Async++ in your application

To use Async++ in your application, you need to add the include directory to your project's include paths and link with the Async++ library. If you are using CMake you can instead include() the export script Async++.cmake that is generated by the build processs. This will make an Async++ target available which will also set appropriate preprocessor flags when you link to it.

Using Async++ in your code is simply a matter of including async++.h. Some parts of the library can be controlled by preprocessor macros that must be defined before including the header:

Macro	Description
LIBASYNC_STATIC	Define this macro if you are linking against a static library version of Async++. Not defining LIBASYNC_STATIC when linking against a static library may cause linker errors on Windows.
LIBASYNC_NO_EXCEPTIONS	Define this macro if you want to disable exception support in Async++. When exceptions are disabled, any operation that would normally cause an exception to be thrown will instead call std::abort. This option is automatically enabled when compiling with exceptions disabled (-fno-exceptions on GCC and defining _HAS_EXCEPTIONS=0 on MSVC). Note that a library compiled with exceptions enabled can be used without problems even if your application is compiled with exceptions disabled.
LIBASYNC_CUSTOM_DEFAULT_SCHEDULER	Define this macro if you want to override Async++'s default scheduler. This will leave the async::default_scheduler function undefined. You must provide a forward declaration for this function before including async++.h.
NDEBUG	Define this macro to remove validity checks from some functions. For example task::get() will check that the task object is valid and throw a std::logic_error exception if it is not. With NDEBUG, this would probably result in a crash instead.

You can control the number of threads spawned in the default scheduler by setting the LIBASYNC_NUM_THREADS environment variable. If this variable is not set then the number of core/hardware threads on the system is used instead.

Note for Windows XP/2003

Async++ uses thread-local storage (TLS) internally, which has some issues in pre-Vista versions of Windows. In particular, dynamically loading DLLs that use TLS with LoadLibrary() will cause crashes. You can still use Async++ in these versions of Windows, but you must then make sure that Async++ is linked directly to your executable and not to a DLL that is loaded at runtime.