Configuring and building the library

Notes about compiler-supplied intrinsics for TLS
Selecting threading API on Windows

Most of the components provided by the library are header-only and do not require linking with Boost.Sync. Currently at_thread_exit, notify_all_at_thread_exit and thread_specific_ptr require linking with prebuilt library. In order to build Boost.Sync, follow the common Getting Started guide for your platform.

Boost.Sync supports a number of macros to configure its implementation and behavior. These macros are given in the following table. These macros should be defined similarly when building Boost and your code using Boost.Sync.

Table 1.1. Configuration macros

Macro name	Effect
`BOOST_USE_WINAPI_VERSION`	This macro is Windows-specific. Selects the target Windows version for various Boost libraries, including Boost.Sync. Code compiled for a particular Windows version will likely fail to run on the older Windows versions, but may improve performance because of using newer OS features. The macro is expected to have an integer value equivalent to `_WIN32_WINNT`.
`BOOST_SYNC_USE_COMPILER_TLS`	This macro enables support for compiler intrinsics for thread-local storage. Defining it may improve performance of Boost.Sync if certain usage limitations are acceptable. See below for more comments.
`BOOST_SYNC_USE_PTHREAD`	This macro forces using pthreads API on Windows. See below for more details.
`BOOST_SYNC_USE_STD_SYSTEM_ERROR`	When defined, instructs Boost.Sync to use `std::system_error` and `std::error_code` instead of Boost.System.

You can define configuration macros in the b2 command line, like this:

b2 -j8 --with-sync variant=release define=BOOST_SYNC_USE_COMPILER_TLS define=BOOST_USE_WINAPI_VERSION=0x0601 stage

Notes about compiler-supplied intrinsics for TLS

Many widely used compilers support builtin intrinsics for managing thread-local storage, which is used in the components of the library which require TLS. This feature is also included in the C++11 standard. Generally, these intrinsics allow for a much more efficient access to the storage than any surrogate implementation, including native operating system API. However, this feature has several caveats:

Some operating systems don't support the use of these intrinsics in case if the TLS is defined in a shared library that is dynamically loaded during the application run time. These systems include Linux and Windows prior to Vista. Windows Vista and later do not have this issue.
The TLS may not be reliably accessed from global constructors and destructors. At least MSVC 8.0 on Windows is known to have this problem.

The library provides the BOOST_SYNC_USE_COMPILER_TLS configuration macro that allows to enable the use of this feature, which will improve the library performance at the cost of these limitations:

The application executable must be linked with the Boost.Log library. It should not be loaded dynamically during run time.
The application must not use TLS in global constructors or destructors.

Note that enabling builtin compiler support for TLS does not remove the dependency on lower level OS threading primitives implementing TLS. The purpose of using compiler intrinsics for TLS is better performance rather than reducing dependencies.

Selecting threading API on Windows

Boost.Sync supports building against one of the following underlying APIs: pthreads or Windows API. On most platforms pthreads are the only option. On Windows, Windows API is used by default, but pthreads can be enabled. One implementation of pthreads on Windows is pthreads-win32.

	Note
	Cygwin is considered a POSIX-compatible platform, which provides pthreads API.

To select pthreads on Windows, do the following:

Set PTW32_INCLUDE variable to the path to pthread-win32 headers and PTW32_LIB to the path to pthread-win32 library. These variables can be set in the environment, user-config.jam or site-config.jam. For example, add the following lines to your user-config.jam (delimiting spaces are significant):

PTW32_INCLUDE = "C:\Program Files\ptw32\Pre-built2\include" ;
PTW32_LIB = "C:\Program Files\ptw32\Pre-built2\lib" ;

Add threadapi=pthread to b2 command line, for example:

b2 -j8 --with-sync variant=release threadapi=pthread stage

When building your code that uses Boost.Sync, define BOOST_SYNC_USE_PTHREAD macro. Make sure paths to pthread-win32 headers and libraries are also configured in your project and you're linking with pthread-win32 pre-built library.

Boost C++ Libraries