| Home | Libraries | People | FAQ | More

## Using and building the library

Boost.Thread is configured following the conventions used to build libraries with separate source code. Boost.Thread will import/export the code only if the user has specifically asked for it, by defining either BOOST_ALL_DYN_LINK if they want all boost libraries to be dynamically linked, or BOOST_THREAD_DYN_LINK if they want just this one to be dynamically liked.

The definition of these macros determines whether BOOST_THREAD_USE_DLL is defined. If BOOST_THREAD_USE_DLL is not defined, the library will define BOOST_THREAD_USE_DLL or BOOST_THREAD_USE_LIB depending on whether the platform. On non windows platforms BOOST_THREAD_USE_LIB is defined if is not defined. In windows platforms, BOOST_THREAD_USE_LIB is defined if BOOST_THREAD_USE_DLL and the compiler supports auto-tss cleanup with Boost.Threads (for the time been Msvc and Intel)

The source code compiled when building the library defines a macros BOOST_THREAD_SOURCE that is used to import or export it. The user must not define this macro in any case.

Boost.Thread depends on some non header-only libraries.

- Boost.System: This dependency is mandatory and you will need to link with the library.
- Boost.Chrono: This dependency is optional (see below how to configure) and you will need to link with the library if you use some of the time related interfaces.
- Boost.DateTime: This dependency is mandatory, but even if Boost.DateTime is a non header-only library Boost.Thread uses only parts that are header-only, so in principle you should not need to link with the library.

It seems that there are some IDE (as e.g. Visual Studio) that deduce the libraries that a program needs to link to inspecting the sources. Such IDE could force to link to Boost.DateTime and/or Boost.Chrono.

As the single mandatory dependency is to Boost.System, the following

    bjam toolset=msvc-11.0 --build-type=complete --with-thread

will install only boost_thread and boost_system.

Users of such IDE should force the Boost.Chrono and Boost.DateTime build using

    bjam toolset=msvc-11.0 --build-type=complete --with-thread --with-chrono --with-date_time

The following section describes all the macros used to configure Boost.Thread.

### Configuration

#### Boost.Chrono

Boost.Thread uses by default Boost.Chrono for the time related functions. For backward compatibility and also for compilers that don't work well with Boost.Chrono the user can define `BOOST_THREAD_DONT_USE_CHRONO`.

`BOOST_THREAD_USES_CHRONO` is defined when Boost.Thread uses Boost.Chrono.

#### Boost.Move

Boost.Thread uses by default an internal move semantic implementation. Since version 3.0.0 you can use the move emulation emulation provided by Boost.Move.

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_USES_MOVE` if you want to use Boost.Move interface. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_USE_MOVE` if you don't want to use Boost.Move interface.

#### Shared Locking Generic

The shared mutex implementation on Windows platform provides currently less functionality than the generic one that is used for PTheads based platforms. In order to have access to these functions, the user needs to define `BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN` to use the generic implementation, that while could be less efficient, provides all the functions.

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN` if you want these features. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_GENERIC_SHARED_MUTEX_ON_WIN` if you don't want these features.

#### Shared Locking Upwards Conversion

Boost.Threads includes in version 3 the Shared Locking Upwards Conversion as defined in Shared Locking. These conversions need to be used carefully to avoid deadlock or livelock. The user need to define explicitly `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION` to get these upwards conversions.

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION` if you want these features. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_SHARED_MUTEX_UPWARDS_CONVERSION` if you don't want these features.

#### Explicit Lock Conversion

In Shared Locking the lock conversions are explicit. As this explicit conversion breaks the lock interfaces, it is provided only if the `BOOST_THREAD_PROVIDES_EXPLICIT_LOCK_CONVERSION` is defined.

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_EXPLICIT_LOCK_CONVERSION` if you want these features. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_EXPLICIT_LOCK_CONVERSION` if you don't want these features.

#### unique_future versus future

C++11 uses `std::future`. Versions of Boost.Thread previous to version 3.0.0 uses `boost:unique_future`. Since version 3.0.0 `boost::future` replaces `boost::unique_future` when `BOOST_THREAD_PROVIDES_FUTURE` is defined. The documentation doesn't contains anymore however `boost::unique_future`.

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_FUTURE` if you want to use boost::future. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_FUTURE` if you want to use boost::unique_future.

#### promise lazy initialization

C++11 promise initialize the associated state at construction time. Versions of Boost.Thread previous to version 3.0.0 initialize it lazily at any point in time in which this associated state is needed.

Since version 3.0.0 this difference in behavior can be configured. When `BOOST_THREAD_PROVIDES_PROMISE_LAZY` is defined the backward compatible behavior is provided.

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_DONT_PROVIDE_PROMISE_LAZY` if you want to use boost::future. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_PROVIDES_PROMISE_LAZY` if you want to use boost::unique_future.

#### promise Allocator constructor

C++11 std::promise provides constructors with allocators.

    template <typename R>
    class promise
    {
      public:
        template <class Allocator>
        explicit promise(allocator_arg_t, Allocator a);
      // ...
    };
    template <class R, class Alloc> struct uses_allocator<promise<R>,Alloc>: true_type {};

where

    struct allocator_arg_t { };
    constexpr allocator_arg_t allocator_arg = allocator_arg_t();

    template <class T, class Alloc> struct uses_allocator;

Since version 3.0.0 Boost.Thread implements this constructor using the following interface

    namespace boost
    {
      typedef container::allocator_arg_t allocator_arg_t;
      constexpr allocator_arg_t allocator_arg = {};

      namespace container
      {
        template <class R, class Alloc>
        struct uses_allocator<promise<R>,Alloc>: true_type {};
      }
      template <class T, class Alloc>
      struct uses_allocator : public container::uses_allocator<T, Alloc> {};
    }

which introduces a dependency on Boost.Container. This feature is provided only if `BOOST_THREAD_PROVIDES_FUTURE_CTOR_ALLOCATORS` is defined.

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_FUTURE_CTOR_ALLOCATORS` if you want these features. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_FUTURE_CTOR_ALLOCATORS` if you don't want these features.

#### Call to terminate if joinable

C++11 has a different semantic for the thread destructor and the move assignment. Instead of detaching the thread, calls to terminate() if the thread was joinable. When `BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE` and `BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE` is defined Boost.Thread provides the C++ semantic.

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE` if you want these features. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE` if you don't want these features.

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE` if you want these features. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE` if you don't want these features.

#### once_flag

C++11 defines a default constructor for once_flag. When `BOOST_THREAD_PROVIDES_ONCE_CXX11` is defined Boost.Thread provides this C++ semantics. In this case, the previous aggregate syntax is not supported.

    boost::once_flag once = BOOST_ONCE_INIT;

You should now just do

    boost::once_flag once;

When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_ONCE_CXX11` if you want these features. When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_ONCE_CXX11` if you don't want these features.

#### Deprecated

Version 3.0.0 deprecates some Boost.Thread features.

These deprecated features will be provided by default up to boost 1.52. If you don't want to include the deprecated features you could define `BOOST_THREAD_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V3_0_0`. Since 1.53 these features will not be included any more by default. Since this version, if you want to include the deprecated features yet you could define `BOOST_THREAD_PROVIDE_DEPRECATED_FEATURES_SINCE_V3_0_0`. These deprecated features will be only available until boost 1.55, that is you have 1 year and a half to move to the new features.

#### Version

`BOOST_THREAD_VERSION` defines the Boost.Thread version. The default version is 2. In this case the following breaking or extending macros are defined if the opposite is not requested:

- `BOOST_THREAD_PROVIDES_PROMISE_LAZY`
- `BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0`

The user can request the version 3 by defining `BOOST_THREAD_VERSION` to 3. In this case the following breaking or extending macros are defined if the opposite is not requested:

- Breaking change `BOOST_THREAD_PROVIDES_EXPLICIT_LOCK_CONVERSION`
- Breaking change `BOOST_THREAD_PROVIDES_FUTURE`
- Uniformity `BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN`
- Extension `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION`
- Conformity `BOOST_THREAD_PROVIDES_FUTURE_CTOR_ALLOCATORS`
- Breaking change BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE
- Breaking change BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE
- Breaking change `BOOST_THREAD_PROVIDES_ONCE_CXX11`
- Breaking change `BOOST_THREAD_DONT_PROVIDE_PROMISE_LAZY`
- Breaking change `BOOST_THREAD_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V3_0_0`

The default value for `BOOST_THREAD_VERSION` will be changed to 3 since Boost 1.53.

### Limitations

Some compilers don't work correctly with some of the added features.

#### SunPro

If __SUNPRO_CC < 0x5100 the library defines

- `BOOST_THREAD_DONT_USE_MOVE`

If __SUNPRO_CC < 0x5100 the library defines

- `BOOST_THREAD_DONT_PROVIDE_FUTURE_CTOR_ALLOCATORS`

#### VACPP

If __IBMCPP__ < 1100 the library defines

- `BOOST_THREAD_DONT_USE_CHRONO`

And Boost.Thread doesn't links with Boost.Chrono.