-
Notifications
You must be signed in to change notification settings - Fork 203
Building and installing
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. |
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.
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.