1[/ 2 (C) Copyright 2012-2015 Vicente J. Botet Escriba. 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at 5 http://www.boost.org/LICENSE_1_0.txt). 6] 7 8 9[section:configuration Configuration] 10 11 12[table Default Values for Configurable Features 13 [[Feature] [Anti-Feature] [V2] [V3] [V4] [V5] ] 14 [[USES_CHRONO] [DONT_USE_CHRONO] [YES/NO] [YES/NO] [YES/NO] [YES/NO] ] 15 [[PROVIDES_INTERRUPTIONS] [DONT_PROVIDE_INTERRUPTIONS] [YES] [YES] [YES] [YES] ] 16 [[THROW_IF_PRECONDITION_NOT_SATISFIED] [-] [NO] [NO] [NO] [NO] ] 17 18 19 20 [[PROVIDES_PROMISE_LAZY] [DONT_PROVIDE_PROMISE_LAZY] [YES] [NO] [NO] [NO] ] 21 22 [[PROVIDES_BASIC_THREAD_ID] [DONT_PROVIDE_BASIC_THREAD_ID] [NO] [YES] [YES] [YES] ] 23 [[PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN] [DONT_PROVIDE_GENERIC_SHARED_MUTEX_ON_WIN] [NO] [YES] [YES] [YES] ] 24 25 [[PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION] [DONT_PROVIDE_SHARED_MUTEX_UPWARDS_CONVERSION] [NO] [YES] [YES] [YES] ] 26 [[PROVIDES_EXECUTORS] [-] [NO] [NO] [NO] [YES] ] 27 [[PROVIDES_EXPLICIT_LOCK_CONVERSION] [DONT_PROVIDE_EXPLICIT_LOCK_CONVERSION] [NO] [YES] [YES] [YES] ] 28 [[PROVIDES_FUTURE] [DONT_PROVIDE_FUTURE] [NO] [YES] [YES] [YES] ] 29 [[PROVIDES_FUTURE_CTOR_ALLOCATORS] [DONT_PROVIDE_FUTURE_CTOR_ALLOCATORS] [NO] [YES] [YES] [YES] ] 30 [[PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE] [DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE] [NO] [YES] [YES] [YES] ] 31 [[PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE] [DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE] [NO] [YES] [YES] [YES] ] 32 [[PROVIDES_ONCE_CXX11] [DONT_PROVIDE_ONCE_CXX11] [NO] [YES] [YES] [YES] ] 33 [[USES_MOVE] [DONT_USE_MOVE] [NO] [YES] [YES] [YES] ] 34 35 [[USES_DATETIME] [DONT_USE_DATETIME] [YES/NO] [YES/NO] [YES/NO] [YES/NO] ] 36 [[PROVIDES_THREAD_EQ] [DONT_PROVIDE_THREAD_EQ] [YES] [YES] [NO] [NO] ] 37 [[PROVIDES_CONDITION] [DONT_PROVIDE_CONDITION] [YES] [YES] [NO] [NO] ] 38 [[PROVIDES_NESTED_LOCKS] [DONT_PROVIDE_NESTED_LOCKS] [YES] [YES] [NO] [NO] ] 39 [[PROVIDES_SIGNATURE_PACKAGED_TASK] [DONT_PROVIDE_SIGNATURE_PACKAGED_TASK] [NO] [NO] [YES] [YES] ] 40 [[PROVIDES_FUTURE_INVALID_AFTER_GET] [DONT_PROVIDE_FUTURE_INVALID_AFTER_GET] [NO] [NO] [YES] [YES] ] 41 [/ [[PROVIDES_FUTURE_CONTINUATION] [DONT_PROVIDE_FUTURE_CONTINUATION] [NO] [NO] [YES] [YES] ] ] 42 43 [[PROVIDES_VARIADIC_THREAD] [DONT_PROVIDE_VARIADIC_THREAD] [NO] [NO] [C++11] [C++11] ] 44 45] 46 47[section:chrono Boost.Chrono] 48 49Boost.Thread uses by default Boost.Chrono for the time related functions and define `BOOST_THREAD_USES_CHRONO` if `BOOST_THREAD_DONT_USE_CHRONO` is not defined. The user should define `BOOST_THREAD_DONT_USE_CHRONO` for compilers that don't work well with Boost.Chrono. 50 51[warning When defined BOOST_THREAD_PLATFORM_WIN32 BOOST_THREAD_USES_CHRONO is defined independently of user settings.] 52 53[endsect] 54 55 56[section:move Boost.Move] 57 58Boost.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. 59 60When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_USES_MOVE ` if you want to use Boost.Move interface. 61When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_USE_MOVE ` if you don't want to use Boost.Move interface. 62 63[endsect] 64 65[section:date_time Boost.DateTime] 66 67The Boost.DateTime time related functions introduced in Boost 1.35.0, using the [link date_time Boost.Date_Time] library are deprecated. These include (but are not limited to): 68 69* __sleep__ 70* __timed_join__ 71* __cond_timed_wait__ 72* __timed_lock_ref__ 73 74 75When `BOOST_THREAD_VERSION<=3` && defined BOOST_THREAD_PLATFORM_PTHREAD define `BOOST_THREAD_DONT_USE_DATETIME` if you don't want to use Boost.DateTime related interfaces. 76When `BOOST_THREAD_VERSION>3` && defined BOOST_THREAD_PLATFORM_PTHREAD define `BOOST_THREAD_USES_DATETIME` if you want to use Boost.DateTime related interfaces. 77 78[warning When defined BOOST_THREAD_PLATFORM_WIN32 BOOST_THREAD_USES_DATETIME is defined independently of user settings.] 79 80[endsect] 81 82[section:move Boost.Atomic] 83 84Boost.Thread uses by default Boost.Atomic in POSIX platforms to implement call_once.. 85 86Define `BOOST_THREAD_USES_ATOMIC ` if you want to use Boost.Atomic. 87Define `BOOST_THREAD_DONT_USE_ATOMIC ` if you don't want to use Boost.Atomic or if it is not supported in your platform. 88 89[endsect] 90 91[section:thread_eq `boost::thread::operator==` deprecated] 92 93The following operators are deprecated: 94 95* `boost::thread::operator==` 96* `boost::thread::operator!=` 97 98When `BOOST_THREAD_PROVIDES_THREAD_EQ` is defined Boost.Thread provides these deprecated feature. 99 100Use instead 101 102* `boost::thread::id::operator==` 103* `boost::thread::id::operator!=` 104 105[warning This is a breaking change respect to version 1.x.] 106 107When `BOOST_THREAD_VERSION>=4` define `BOOST_THREAD_PROVIDES_THREAD_EQ ` if you want this feature. 108When `BOOST_THREAD_VERSION<4` define `BOOST_THREAD_DONT_PROVIDE_THREAD_EQ ` if you don't want this feature. 109 110[endsect] 111 112[section:condition boost::condition deprecated] 113 114`boost::condition` is deprecated. When `BOOST_THREAD_PROVIDES_CONDITION` is defined Boost.Thread provides this deprecated feature. 115 116Use instead `boost::condition_variable_any`. 117 118[warning This is a breaking change respect to version 1.x.] 119 120When `BOOST_THREAD_VERSION>3` define `BOOST_THREAD_PROVIDES_CONDITION` if you want this feature. 121When `BOOST_THREAD_VERSION<=3` define `BOOST_THREAD_DONT_PROVIDE_CONDITION` if you don't want this feature. 122 123[endsect] 124 125[section:nested_lock Mutex nested lock types deprecated] 126 127 128The following nested typedefs are deprecated: 129 130* `boost::mutex::scoped_lock`, 131* `boost::mutex::scoped_try_lock`, 132* `boost::timed_mutex::scoped_lock` 133* `boost::timed_mutex::scoped_try_lock` 134* `boost::timed_mutex::timed_scoped_timed_lock` 135* `boost::recursive_mutex::scoped_lock`, 136* `boost::recursive_mutex::scoped_try_lock`, 137* `boost::recursive_timed_mutex::scoped_lock` 138* `boost::recursive_timed_mutex::scoped_try_lock` 139* `boost::recursive_timed_mutex::timed_scoped_timed_lock` 140 141When `BOOST_THREAD_PROVIDES_NESTED_LOCKS` is defined Boost.Thread provides these deprecated feature. 142 143 144Use instead 145* `boost::unique_lock<boost::mutex>`, 146* `boost::unique_lock<boost::mutex>` with the `try_to_lock_t` constructor, 147* `boost::unique_lock<boost::timed_mutex>` 148* `boost::unique_lock<boost::timed_mutex>` with the `try_to_lock_t` constructor 149* `boost::unique_lock<boost::timed_mutex>` 150* `boost::unique_lock<boost::recursive_mutex>`, 151* `boost::unique_lock<boost::recursive_mutex>` with the `try_to_lock_t` constructor, 152* `boost::unique_lock<boost::recursive_timed_mutex>` 153* `boost::unique_lock<boost::recursive_timed_mutex>` with the `try_to_lock_t` constructor 154* `boost::unique_lock<boost::recursive_timed_mutex>` 155 156[warning This is a breaking change respect to version 1.x.] 157 158When `BOOST_THREAD_VERSION>=4` define `BOOST_THREAD_PROVIDES_NESTED_LOCKS` if you want these features. 159When `BOOST_THREAD_VERSION<4` define `BOOST_THREAD_DONT_PROVIDE_NESTED_LOCKS` if you don't want thes features. 160 161[endsect] 162 163[section:id thread::id] 164 165Boost.Thread uses by default a thread::id on Posix based on the pthread type (BOOST_THREAD_PROVIDES_BASIC_THREAD_ID). For backward compatibility and also for compilers that don't work well with this modification the user can define `BOOST_THREAD_DONT_PROVIDE_BASIC_THREAD_ID`. 166 167Define `BOOST_THREAD_DONT_PROVIDE_BASIC_THREAD_ID ` if you don't want these features. 168 169[endsect] 170[section:shared_gen Shared Locking Generic] 171 172The 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. 173 174When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN ` if you want these features. 175When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_GENERIC_SHARED_MUTEX_ON_WIN ` if you don't want these features. 176 177[endsect] 178 179[section:shared_upwards Shared Locking Upwards Conversion] 180 181Boost.Threads includes in version 3 the Shared Locking Upwards Conversion as defined in [@http://home.roadrunner.com/~hinnant/bloomington/shared_mutex.html Shared Locking]. 182These conversions need to be used carefully to avoid deadlock or livelock. The user need to define explicitly `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSIONS` to get these upwards conversions. 183 184When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSIONS ` if you want these features. 185When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_SHARED_MUTEX_UPWARDS_CONVERSION ` if you don't want these features. 186 187[endsect] 188 189[section:explicit_cnv Explicit Lock Conversion] 190 191In [@http://home.roadrunner.com/~hinnant/bloomington/shared_mutex.html 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. 192 193When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_EXPLICIT_LOCK_CONVERSION ` if you want these features. 194When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_EXPLICIT_LOCK_CONVERSION ` if you don't want these features. 195 196[endsect] 197 198 199[section:future unique_future versus future] 200 201C++11 uses `std::future`. Versions of Boost.Thread previous to version 3.0.0 uses `boost:unique_future`. 202Since 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`. 203 204When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_FUTURE` if you want to use boost::future. 205When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_FUTURE` if you want to use boost::unique_future. 206 207[endsect] 208 209[section:lazy promise lazy initialization] 210 211C++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. 212 213Since 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. 214 215When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_DONT_PROVIDE_PROMISE_LAZY ` if you want to use boost::future. 216When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_PROVIDES_PROMISE_LAZY ` if you want to use boost::unique_future. 217 218[endsect] 219 220[section:alloc promise Allocator constructor] 221 222C++11 std::promise provides constructors with allocators. 223 224 template <typename R> 225 class promise 226 { 227 public: 228 template <class Allocator> 229 explicit promise(allocator_arg_t, Allocator a); 230 // ... 231 }; 232 template <class R, class Alloc> struct uses_allocator<promise<R>,Alloc>: true_type {}; 233 234where 235 236 struct allocator_arg_t { }; 237 constexpr allocator_arg_t allocator_arg = allocator_arg_t(); 238 239 template <class T, class Alloc> struct uses_allocator; 240 241Since version 3.0.0 Boost.Thread implements this constructor using the following interface 242 243 namespace boost 244 { 245 typedef container::allocator_arg_t allocator_arg_t; 246 constexpr allocator_arg_t allocator_arg = {}; 247 248 namespace container 249 { 250 template <class R, class Alloc> 251 struct uses_allocator<promise<R>,Alloc>: true_type {}; 252 } 253 template <class T, class Alloc> 254 struct uses_allocator : public container::uses_allocator<T, Alloc> {}; 255 } 256 257which introduces a dependency on Boost.Container. This feature is provided only if `BOOST_THREAD_PROVIDES_FUTURE_CTOR_ALLOCATORS` is defined. 258 259When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_FUTURE_CTOR_ALLOCATORS ` if you want these features. 260When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_FUTURE_CTOR_ALLOCATORS ` if you don't want these features. 261 262[endsect] 263 264[section:terminate Call to terminate if joinable] 265 266C++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. 267 268When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE ` if you want these features. 269When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE ` if you don't want these features. 270 271When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE ` if you want these features. 272When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE ` if you don't want these features. 273 274[endsect] 275 276[section:once_flag once_flag] 277 278C++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. 279 280 boost::once_flag once = BOOST_ONCE_INIT; 281 282You should now just do 283 284 boost::once_flag once; 285 286When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_ONCE_CXX11` if you want these features. 287When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_ONCE_CXX11` if you don't want these features. 288 289[endsect] 290 291 292[section:deprecated Signature parameter for packaged_task] 293 294C++11 packaged task class has a Signature template parameter. When `BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK ` is defined Boost.Thread provides this C++ feature. 295 296[warning This is a breaking change respect to version 3.x.] 297 298When `BOOST_THREAD_VERSION<4` define `BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK` if you want this feature. 299When `BOOST_THREAD_VERSION>=4` define `BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK` if you don't want this feature. 300 301[endsect] 302 303 304[section:thread_const-var thread constructor with variadic rvalue parameters] 305 306C++11 thread constructor accept a variable number of rvalue arguments has. When `BOOST_THREAD_PROVIDES_VARIADIC_THREAD ` is defined Boost.Thread provides this C++ feature if the following are not defined 307 308* BOOST_NO_SFINAE_EXPR 309* BOOST_NO_CXX11_VARIADIC_TEMPLATES 310* BOOST_NO_CXX11_DECLTYPE 311* BOOST_NO_CXX11_DECLTYPE_N3276 312* BOOST_NO_CXX11_RVALUE_REFERENCES 313* BOOST_NO_CXX11_TRAILING_RESULT_TYPES 314* BOOST_NO_CXX11_RVALUE_REFERENCES 315* BOOST_NO_CXX11_HDR_TUPLE 316 317When `BOOST_THREAD_VERSION>4` define `BOOST_THREAD_DONT_PROVIDE_VARIADIC_THREAD ` if you don't want this feature. 318 319[endsect] 320 321[section:get_invalid future<>::get() invalidates the future] 322 323C++11 future<>::get() invalidates the future once its value has been obtained. When `BOOST_THREAD_PROVIDES_FUTURE_INVALID_AFTER_GET ` is defined Boost.Thread provides this C++ feature. 324 325[warning This is a breaking change respect to version 3.x.] 326 327When `BOOST_THREAD_VERSION<4` define `BOOST_THREAD_PROVIDES_FUTURE_INVALID_AFTER_GET` if you want this feature. 328When `BOOST_THREAD_VERSION>=4` define `BOOST_THREAD_DONT_PROVIDE_FUTURE_INVALID_AFTER_GET` if you don't want this feature. 329 330[endsect] 331 332[section:intr Interruptions] 333 334Thread interruption, while useful, makes any interruption point less efficient than if the thread were not interruptible. 335 336When `BOOST_THREAD_PROVIDES_INTERRUPTIONS` is defined Boost.Thread provides interruptions. 337When `BOOST_THREAD_DONT_PROVIDE_INTERRUPTIONS` is defined Boost.Thread don't provide interruption. 338 339Boost.Thread defines BOOST_THREAD_PROVIDES_INTERRUPTIONS if neither BOOST_THREAD_PROVIDES_INTERRUPTIONS nor BOOST_THREAD_DONT_PROVIDE_INTERRUPTIONS are defined, so that there is no compatibility break. 340 341[endsect] 342 343[section:version Version] 344 345`BOOST_THREAD_VERSION` defines the Boost.Thread version. 346The default version is 2. In this case the following breaking or extending macros are defined if the opposite is not requested: 347 348* `BOOST_THREAD_PROVIDES_PROMISE_LAZY` 349 350The 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: 351 352* Breaking change `BOOST_THREAD_PROVIDES_EXPLICIT_LOCK_CONVERSION ` 353* Conformity & Breaking change `BOOST_THREAD_PROVIDES_FUTURE` 354* Uniformity `BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN` 355* Extension `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSIONS` 356* Conformity `BOOST_THREAD_PROVIDES_FUTURE_CTOR_ALLOCATORS` 357* Conformity & Breaking change BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE 358* Conformity & Breaking change BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE 359* Conformity & Breaking change `BOOST_THREAD_PROVIDES_ONCE_CXX11` 360 361* Breaking change `BOOST_THREAD_DONT_PROVIDE_PROMISE_LAZY` 362 363[/The default value for `BOOST_THREAD_VERSION` will be changed to 3 since Boost 1.54.] 364 365The user can request the version 4 by defining `BOOST_THREAD_VERSION` to 4. In this case the following breaking or extending macros are defined if the opposite is not requested: 366 367* Conformity & Breaking change `BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK ` 368* Conformity & Breaking change `BOOST_THREAD_PROVIDES_FUTURE_INVALID_AFTER_GET ` 369* Conformity `BOOST_THREAD_PROVIDES_VARIADIC_THREAD` 370* Breaking change `BOOST_THREAD_DONT_PROVIDE_THREAD_EQ` 371* Breaking change `BOOST_THREAD_DONT_USE_DATETIME` 372 373 374[/The default value for `BOOST_THREAD_VERSION` will be changed to 4 since Boost 1.58.] 375 376[endsect] 377 378[endsect] 379 380[section:limitations Limitations] 381 382Some compilers don't work correctly with some of the added features. 383 384[section:sun SunPro] 385 386If __SUNPRO_CC < 0x5100 the library defines 387 388* `BOOST_THREAD_DONT_USE_MOVE` 389 390If __SUNPRO_CC < 0x5100 the library defines 391 392* `BOOST_THREAD_DONT_PROVIDE_FUTURE_CTOR_ALLOCATORS` 393 394 395[endsect] 396[section:vacpp VACPP] 397 398If __IBMCPP__ < 1100 the library defines 399 400* `BOOST_THREAD_DONT_USE_CHRONO` 401* `BOOST_THREAD_USES_DATE` 402 403And Boost.Thread doesn't links with Boost.Chrono. 404 405 406[endsect] 407[section:ce WCE] 408 409If _WIN32_WCE && _WIN32_WCE==0x501 the library defines 410 411* `BOOST_THREAD_DONT_PROVIDE_FUTURE_CTOR_ALLOCATORS` 412 413 414[endsect] 415 416[endsect] 417