Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 31c6e1f53a.
PrevUpHomeNext

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

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.

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] 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.

PrevUpHomeNext