ceph/src/boost/libs/thread/doc/scoped_thread.qbk

   1 [/
   2   (C) Copyright 2008-9 Anthony Williams.
   3   (C) Copyright 12 Vicente J. Botet Escriba.
   4   Distributed under the Boost Software License, Version 1.0.
   5   (See accompanying file LICENSE_1_0.txt or copy at
   6   http://www.boost.org/LICENSE_1_0.txt).
   7 ]
   8
   9 [section:ScopedThreads Scoped Threads]
  10
  11 [heading Synopsis]
  12
  13   //#include <boost/thread/scoped_thread.hpp>
  14
  15   struct detach;
  16   struct join_if_joinable;
  17   struct interrupt_and_join_if_joinable;
  18   template <class CallableThread = join_if_joinable>
  19   class strict_scoped_thread;
  20   template <class CallableThread = join_if_joinable>
  21   class scoped_thread;
  22   void swap(scoped_thread& lhs,scoped_thread& rhs) noexcept;
  23
  24 [section:motivation Motivation]
  25 Based on the scoped_thread class defined in C++ Concurrency in Action Boost.Thread defines a thread wrapper class that instead of calling terminate if the thread is joinable on destruction, call a specific action given as template parameter.
  26
  27 While the scoped_thread class defined in C++ Concurrency in Action is closer to strict_scoped_thread class that doesn't allows any change in the wrapped thread, Boost.Thread provides a class scoped_thread that provides the same non-deprecated interface as __thread.
  28
  29 [endsect]
  30
  31 [section:tutorial Tutorial]
  32
  33 Scoped Threads are wrappers around a thread that allows the user to state what to do at destruction time. One of the common uses is to join the thread at destruction time so this is the default behavior. This is the single difference respect to a thread. While thread call std::terminate() on the destructor if the thread is joinable, strict_scoped_thread<> or scoped_thread<> join the thread if joinable.
  34
  35 The difference between strict_scoped_thread and scoped_thread is that the strict_scoped_thread hides completely the owned thread and so the user can do nothing with the owned thread other than the specific action given as parameter, while scoped_thread provide the same interface as __thread and forwards all the operations.
  36
  37   boost::strict_scoped_thread<> t1((boost::thread(f)));
  38   //t1.detach(); // compile fails
  39   boost::scoped_thread<> t2((boost::thread(f)));
  40   t2.detach();
  41
  42 [endsect]
  43
  44 [section:thread_functors Free Thread Functors]
  45
  46   //#include <boost/thread/scoped_thread.hpp>
  47
  48   struct detach;
  49   struct join_if_joinable;
  50   struct interrupt_and_join_if_joinable;
  51
  52
  53 [section:detach Functor `detach`]
  54
  55   struct detach
  56   {
  57     void operator()(thread& t)
  58     {
  59       t.detach();
  60     }
  61   };
  62 [endsect]
  63 [section:join_if_joinable Functor `join_if_joinable`]
  64
  65   struct join_if_joinable
  66   {
  67     void operator()(thread& t)
  68     {
  69       if (t.joinable())
  70       {
  71         t.join();
  72       }
  73     }
  74   };
  75
  76 [endsect]
  77
  78 [section:interrupt_and_join_if_joinable Functor `interrupt_and_join_if_joinable`]
  79
  80   struct interrupt_and_join_if_joinable
  81   {
  82     void operator()(thread& t)
  83     {
  84       t.interrupt();
  85       if (t.joinable())
  86       {
  87         t.join();
  88       }
  89     }
  90   };
  91 [endsect]
  92
  93 [endsect]
  94
  95 [section:strict_scoped_thread Class `strict_scoped_thread`]
  96
  97   // #include <boost/thread/scoped_thread.hpp>
  98
  99   template <class CallableThread = join_if_joinable>
 100   class strict_scoped_thread
 101   {
 102     thread t_; // for exposition purposes only
 103   public:
 104
 105     strict_scoped_thread(strict_scoped_thread const&) = delete;
 106     strict_scoped_thread& operator=(strict_scoped_thread const&) = delete;
 107
 108     explicit strict_scoped_thread(thread&& t) noexcept;
 109     template <typename F&&, typename ...Args>
 110     explicit strict_scoped_thread(F&&, Args&&...);
 111
 112     ~strict_scoped_thread();
 113
 114   };
 115
 116
 117 RAII __thread wrapper adding a specific destroyer allowing to master what can be done at destruction time.
 118
 119 CallableThread: A callable `void(thread&)`.
 120
 121 The default is a `join_if_joinable`.
 122
 123
 124 Thread destructor terminates the program if the __thread is joinable.
 125 This wrapper can be used to join the thread before destroying it.
 126
 127 [heading Example]
 128
 129   boost::strict_scoped_thread<> t((boost::thread(F)));
 130
 131 [section:default_constructor Constructor from a __thread]
 132
 133     explicit strict_scoped_thread(thread&& t) noexcept;
 134
 135 [variablelist
 136
 137 [[Effects:] [move the thread to own `t_`]]
 138
 139 [[Throws:] [Nothing]]
 140
 141 ]
 142
 143 [endsect]
 144
 145
 146 [section:call_constructor Move Constructor from a Callable]
 147
 148         template <typename F&&, typename ...Args>
 149         explicit strict_scoped_thread(F&&, Args&&...);
 150
 151 [variablelist
 152
 153 [[Effects:] [Construct an internal thread in place.]]
 154
 155 [[Postconditions:] [`*this.t_` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.]]
 156
 157 [[Throws:] [Any exception the thread construction can throw.]]
 158
 159 ]
 160
 161 [endsect]
 162
 163 [section:destructor Destructor]
 164
 165     ~strict_scoped_thread();
 166
 167 [variablelist
 168
 169 [[Effects:] [Equivalent to `CallableThread()(t_)`.  ]]
 170
 171 [[Throws:] [Nothing: The `CallableThread()(t_)` should not throw when joining the thread as the scoped variable is on a scope outside the thread function.]]
 172
 173 ]
 174
 175 [endsect]
 176
 177 [endsect]
 178
 179 [section:scoped_thread Class `scoped_thread`]
 180
 181     #include <boost/thread/scoped_thread.hpp>
 182
 183     template <class CallableThread>
 184     class scoped_thread
 185     {
 186       thread t_; // for exposition purposes only
 187     public:
 188         scoped_thread() noexcept;
 189         scoped_thread(const scoped_thread&) = delete;
 190         scoped_thread& operator=(const scoped_thread&) = delete;
 191
 192         explicit scoped_thread(thread&& th) noexcept;
 193         template <typename F&&, typename ...Args>
 194         explicit scoped_thread(F&&, Args&&...);
 195
 196         ~scoped_thread();
 197
 198         // move support
 199         scoped_thread(scoped_thread && x) noexcept;
 200         scoped_thread& operator=(scoped_thread && x) noexcept;
 201
 202         void swap(scoped_thread& x) noexcept;
 203
 204         typedef thread::id id;
 205
 206         id get_id() const noexcept;
 207
 208         bool joinable() const noexcept;
 209         void join();
 210     #ifdef BOOST_THREAD_USES_CHRONO
 211         template <class Rep, class Period>
 212         bool try_join_for(const chrono::duration<Rep, Period>& rel_time);
 213         template <class Clock, class Duration>
 214         bool try_join_until(const chrono::time_point<Clock, Duration>& t);
 215     #endif
 216
 217         void detach();
 218
 219         static unsigned hardware_concurrency() noexcept;
 220         static unsigned physical_concurrency() noexcept;
 221
 222         typedef thread::native_handle_type native_handle_type;
 223         native_handle_type native_handle();
 224
 225     #if defined BOOST_THREAD_PROVIDES_INTERRUPTIONS
 226         void interrupt();
 227         bool interruption_requested() const noexcept;
 228     #endif
 229
 230
 231     };
 232
 233     void swap(scoped_thread& lhs,scoped_thread& rhs) noexcept;
 234
 235
 236 RAII __thread wrapper adding a specific destroyer allowing to master what can be done at destruction time.
 237
 238 CallableThread: A callable void(thread&).
 239 The default is join_if_joinable.
 240
 241 Thread destructor terminates the program if the thread is joinable.
 242 This wrapper can be used to join the thread before destroying it.
 243
 244 Remark: `scoped_thread` is not a __thread as __thread is not designed to be derived from as a polymorphic type.
 245
 246 Anyway `scoped_thread` can be used in most of the contexts a __thread could be used as it has the
 247 same non-deprecated interface with the exception of the construction.
 248
 249 [heading Example]
 250
 251   boost::scoped_thread<> t((boost::thread(F)));
 252   t.interrupt();
 253
 254
 255 [section:default_constructor Default Constructor]
 256
 257     scoped_thread() noexcept;
 258
 259 [variablelist
 260
 261 [[Effects:] [Constructs a scoped_thread instance that wraps to __not_a_thread__.]]
 262
 263 [[Postconditions:] [`this->get_id()==thread::id()`]]
 264
 265 [[Throws:] [Nothing]]
 266
 267 ]
 268
 269 [endsect]
 270
 271 [section:move_constructor Move Constructor]
 272
 273     scoped_thread(scoped_thread&& other) noexcept;
 274
 275 [variablelist
 276
 277 [[Effects:] [Transfers ownership of the scoped_thread managed by `other` (if any) to the newly constructed scoped_thread instance.]]
 278
 279 [[Postconditions:] [`other.get_id()==thread::id()` and `get_id()` returns the value of `other.get_id()` prior to the construction]]
 280
 281 [[Throws:] [Nothing]]
 282
 283 ]
 284
 285 [endsect]
 286
 287 [section:move_assignment Move assignment operator]
 288
 289     scoped_thread& operator=(scoped_thread&& other) noexcept;
 290
 291 [variablelist
 292
 293 [[Effects:] [Transfers ownership of the scoped_thread managed by `other` (if
 294 any) to `*this` after having called to `CallableThread()(t_)`.
 295
 296 ]]
 297
 298 [[Postconditions:] [`other->get_id()==thread::id()` and `get_id()` returns the value of `other.get_id()` prior to the assignment.]]
 299
 300 [[Throws:] [Nothing: The `CallableThread()(t_)` should not throw when joining the thread as the scoped variable is on a scope outside the thread function.]]
 301
 302
 303 ]
 304
 305 [endsect]
 306
 307 [section:thread_constructor Move Constructor from a __thread]
 308
 309     scoped_thread(thread&& t);
 310
 311 [variablelist
 312
 313 [[Effects:] [Transfers ownership of the thread managed by `other` (if any) to the newly constructed scoped_thread instance.]]
 314
 315 [[Postconditions:] [other.get_id()==thread::id() and get_id() returns the value of other.get_id() prior to the construction.]]
 316
 317 [[Throws:] [Nothing]]
 318
 319 ]
 320
 321 [endsect]
 322
 323 [section:call_constructor Move Constructor from a Callable]
 324
 325         template <typename F&&, typename ...Args>
 326         explicit scoped_thread(F&&, Args&&...);
 327
 328 [variablelist
 329
 330 [[Effects:] [Construct an internal thread in place.]]
 331
 332 [[Postconditions:] [`*this.t_` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.]]
 333
 334 [[Throws:] [Any exception the thread construction can throw.]]
 335
 336 ]
 337
 338 [endsect]
 339
 340
 341 [section:destructor Destructor]
 342
 343     ~scoped_thread();
 344
 345 [variablelist
 346
 347 [[Effects:] [Equivalent to `CallableThread()(t_)`.  ]]
 348
 349 [[Throws:] [Nothing: The `CallableThread()(t_)` should not throw when joining the thread as the scoped variable is on a scope outside the thread function.]]
 350
 351 ]
 352
 353 [endsect]
 354
 355
 356 [section:joinable Member function `joinable()`]
 357
 358     bool joinable() const noexcept;
 359
 360 [variablelist
 361
 362 [[Returns:] [Equivalent to return t_.joinable().]]
 363
 364 [[Throws:] [Nothing]]
 365
 366 ]
 367
 368
 369 [endsect]
 370
 371 [section:join Member function `join()`]
 372
 373     void join();
 374
 375 [variablelist
 376
 377 [[Effects:] [Equivalent to t_.join().]]
 378
 379 ]
 380
 381 [endsect]
 382
 383 [section:try_join_for Member function `try_join_for()`]
 384
 385         template <class Rep, class Period>
 386         bool try_join_for(const chrono::duration<Rep, Period>& rel_time);
 387
 388 [variablelist
 389
 390 [[Effects:] [Equivalent to return `t_.try_join_for(rel_time)`.]]
 391
 392 ]
 393
 394 [endsect]
 395
 396 [section:try_join_until Member function `try_join_until()`]
 397
 398         template <class Clock, class Duration>
 399         bool try_join_until(const chrono::time_point<Clock, Duration>& abs_time);
 400
 401 [variablelist
 402
 403 [[Effects:] [Equivalent to return `t_.try_join_until(abs_time)`.]]
 404
 405 ]
 406
 407 [endsect]
 408
 409
 410
 411 [section:detach Member function `detach()`]
 412
 413     void detach();
 414
 415 [variablelist
 416
 417 [[Effects:] [Equivalent to `t_.detach()`.]]
 418
 419 ]
 420
 421 [endsect]
 422
 423
 424 [section:get_id Member function `get_id()`]
 425
 426     thread::id get_id() const noexcept;
 427
 428 [variablelist
 429
 430 [[Effects:] [Equivalent to return `t_.get_id()`.]]
 431
 432 ]
 433
 434 [endsect]
 435
 436 [section:interrupt Member function `interrupt()`]
 437
 438     void interrupt();
 439
 440 [variablelist
 441
 442 [[Effects:] [Equivalent to `t_.interrupt()`.]]
 443
 444 ]
 445
 446
 447 [endsect]
 448
 449 [section:hardware_concurrency Static member function `hardware_concurrency()`]
 450
 451     unsigned hardware_concurrency() noexecpt;
 452
 453 [variablelist
 454
 455 [[Effects:] [Equivalent to return `thread::hardware_concurrency()`.]]
 456
 457 ]
 458
 459 [endsect]
 460
 461
 462 [section:physical_concurrency Static member function `physical_concurrency()`]
 463
 464     unsigned physical_concurrency() noexecpt;
 465
 466 [variablelist
 467
 468 [[Effects:] [Equivalent to return `thread::physical_concurrency()`.]]
 469
 470 ]
 471
 472 [endsect]
 473
 474
 475 [section:nativehandle Member function `native_handle()`]
 476
 477     typedef thread::native_handle_type native_handle_type;
 478     native_handle_type native_handle();
 479
 480 [variablelist
 481
 482 [[Effects:] [Equivalent to return `t_.native_handle()`.]]
 483
 484 ]
 485
 486 [endsect]
 487
 488 [section:swap Member function `swap()`]
 489
 490     void swap(scoped_thread& other) noexcept;
 491
 492 [variablelist
 493
 494 [[Effects:] [Equivalent `t_.swap(other.t_)`.]]
 495
 496 ]
 497
 498 [endsect]
 499
 500
 501
 502 [endsect]
 503 [section:non_member_swap Non-member function `swap(scoped_thread&,scoped_thread&)`]
 504
 505     #include <boost/thread/scoped_thread.hpp>
 506
 507     void swap(scoped_thread& lhs,scoped_thread& rhs) noexcept;
 508
 509 [variablelist
 510
 511 [[Effects:] [`lhs.swap(rhs)`.]]
 512
 513 ]
 514
 515 [endsect]
 516 [endsect]