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

   1 [/
   2  / Copyright (c) 2013 Vicente J. Botet Escriba
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [/////////////////////////////////////]
   9 [section:synchronized_queues Synchronized Queues -- EXPERIMENTAL]
  10
  11 [warning These features are experimental and subject to change in future versions. There are not too much tests yet, so it is possible that you can find out some trivial bugs :(]
  12
  13 [note These features are based on the [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3533.html [*N3533 - C++ Concurrent Queues]] C++1y proposal from Lawrence Crowl and Chris Mysen and [@http://www.manning.com/williams/ [*C++ Concurrency in Action]] from Anthony Williams.]
  14
  15
  16 [////////////////////]
  17 [section Introduction]
  18
  19 Queues provide a mechanism for communicating data between components of a system.
  20
  21 The existing deque in the standard library is an inherently sequential data structure. Its reference-returning element access operations cannot synchronize access to those elements with other queue operations. So, concurrent pushes and pops on queues require a different interface to the queue structure.
  22
  23 Moreover, concurrency adds a new dimension for performance and semantics. Different queue implementation must trade off uncontended operation cost, contended operation cost, and element order guarantees. Some of these trade-offs will necessarily result in semantics weaker than a serial queue.
  24
  25 [endsect]
  26
  27 [/////////////////////////////////////]
  28 [section:tutorial Tutorial]
  29
  30 Concurrent queues are a well know mechanism for communicating data between different threads.
  31
  32 Concurrent queues have inherently copy/move semantics for the data handling operation. Reference-returning interfaces are forbidden as multiple access to these references can not be thread-safe.
  33
  34 [endsect]
  35 [////////////////]
  36 [section Examples]
  37
  38
  39 [endsect]
  40
  41 [/////////////////////////////////////]
  42 [section:ref Reference]
  43
  44 [section:sync_queue_req Synchronized Queue Model]
  45
  46 [section:bounded_unbounded Bounded-Unbounded Queues]
  47
  48 One of the major features of a concurrent queue is whether it has a bounded-unbounded capacity.
  49
  50 [endsect]
  51
  52 [section:locking Locking/Lock-free Queues]
  53
  54 Locking queues can by nature block waiting for the queue to be non-empty or non-full.
  55
  56 Lock-free queues will have some trouble waiting for the queue to be non-empty or non-full queues. These queues can not define operations such as push (and pull for bounded queues). That is, it could have blocking operations (presumably emulated with busy wait) but not waiting operations.
  57
  58 [endsect]
  59 [/////////////////////////////////////]
  60 [section:closed Closed Queue]
  61
  62 Threads using a queue for communication need some mechanism to signal when the queue is no longer needed. The usual approach is add an additional out-of-band signal. However, this approach suffers from the flaw that threads waiting on either full or empty queues need to be woken up when the queue is no longer needed. Rather than require an out-of-band signal, we chose to directly support such a signal in the queue itself, which considerably simplifies coding.
  63
  64 To achieve this signal, a thread may close a queue. Once closed, no new elements may be pushed onto the queue. Push operations on a closed queue will either return queue_op_status::closed (when they have a queue_op_status return type), set the closed parameter if it has one or throw sync_queue::closed (when they do not). Elements already on the queue may be pulled off. When a queue is empty and closed, pull operations will either return queue_op_status::closed (when they have a status return), set the closed parameter if it has one or throw sync_queue::closed (when they do not).
  65
  66 [endsect]
  67 [/////////////////////////////////////]
  68 [section:exception Concurrent Queues Throw specification]
  69 [section:locking Locking]
  70
  71 All the functions are defined as if we had in addition to its specific Throw specification the following:
  72
  73 [variablelist
  74 [[Throws:] [Any exception thrown by the internal locking.]]
  75 ]
  76
  77 [endsect]
  78 [/////////////////////////////////////]
  79 [section:bad_alloc Allocation]
  80
  81 All the functions that allocate a resource are defined as if we had in addition to its specific Throw specification the following:
  82
  83 [variablelist
  84 [[Throws:] [Any exception due to allocation errors.]]
  85 ]
  86
  87 [endsect]
  88 [endsect]
  89 [/////////////////////////////////////]
  90 [section:BasicConcurrentQueue Basic Concurrent Queue Operations]
  91
  92 The essential solution to the problem of concurrent queuing is to shift to value-based operations, rather than reference-based operations.
  93
  94 The BasicConcurrentQueue concept models the basic operations of a concurrent queue.
  95
  96 A type `Q` meets the BasicConcurrentQueue requirements if the following expressions are well-formed and have the specified semantics
  97
  98 * Q::value_type
  99 * Q::size_type
 100 * `q.push_back(e);`
 101 * `q.push_back(rve);`
 102 * `q.pull_front(lre);`
 103 * `lre = q.pull_front();`
 104 [/* `spe = q.ptr_pull_front();`]
 105 * `b = q.empty();`
 106 * `u = q.size();`
 107
 108 where
 109
 110 * `q` denotes a value of type `Q`,
 111 * `e` denotes a value of type Q::value_type,
 112 * `u` denotes a value of type Q::size_type,
 113 * `lve` denotes an lvalue reference of type Q::value_type,
 114 * `rve` denotes an rvalue reference of type Q::value_type:
 115 [/* `spe` denotes a shared_ptr<Q::value_type>]
 116 * `qs` denotes a variable of of type `queue_op_status`,
 117
 118
 119 [/////////////////////////////////////]
 120 [section:push_back `q.push_back(e);`]
 121
 122 [variablelist
 123
 124 [[Effects:] [Waits until the queue is not full (for bounded queues) and then push back `e` to the queue copying it (this could need an allocation for unbounded queues).]]
 125
 126 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 127
 128 [[Postcondition:] [`! q.empty()`.]]
 129
 130 [[Return type:] [`void`.]]
 131
 132 [[Throws:] [If the queue was closed, throws sync_queue_is_closed. Any exception thrown by the copy of `e`.]]
 133
 134 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 135
 136 ]
 137
 138 [endsect]
 139 [/////////////////////////////////////]
 140 [section:push_back_m `q.push_back(rve);`]
 141
 142 [variablelist
 143
 144 [[Effects:] [Waits until the queue is not full (for bounded queues) and then push `e` to the queue moving it back in the queue (this could need an allocation for unbounded queues).]]
 145
 146 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 147
 148 [[Postcondition:] [`! q.empty()`.]]
 149
 150 [[Return type:] [`void`.]]
 151
 152 [[Throws:] [If the queue is closed, throws sync_queue_is_closed. Any exception thrown by the copy of `e`.]]
 153
 154 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 155
 156 ]
 157
 158 [endsect]
 159 [/////////////////////////////////////]
 160 [section:pull_front_lv `q.pull_front(lve)`]
 161
 162 [variablelist
 163
 164 [[Effects:] [Waits until the queue is not empty and then pull_front the element from the queue `q` and moves the pulled element into `lve` (this could need an allocation for unbounded queues).]]
 165
 166 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 167
 168 [[Postcondition:] [`! q.full()`.]]
 169
 170 [[Return type:] [`void`.]]
 171
 172 [[Throws:] [Any exception thrown by the move of `e`.]]
 173
 174 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 175
 176 ]
 177
 178 [endsect]
 179 [/////////////////////////////////////]
 180 [section:pull_front `e = q.pull_front()`]
 181
 182 [variablelist
 183
 184 [[Requires:] [Q::value_type is no throw move constructible. This is needed to ensure the exception safety.]]
 185
 186 [[Effects:] [Waits until the queue is not empty and not closed. If the queue is empty and closed throws sync_queue_is_closed. Otherwise pull the element from the queue `q` and moves the pulled element.]]
 187
 188 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 189
 190 [[Postcondition:] [`! q.full()`.]]
 191
 192 [[Return type:] [`Q::value_type`.]]
 193
 194 [[Return:] [The pulled element.]]
 195
 196 [[Throws:] [Any exception thrown by the copy of `e`.]]
 197
 198 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 199
 200 ]
 201
 202 [endsect]
 203 [/
 204 [/////////////////////////////////////]
 205 [section:ptr_pull_front `spe = q.ptr_pull_front()`]
 206
 207 [variablelist
 208
 209 [/[Requires:] [Q::value_type is no throw move assignable. This is needed to ensure the exception safety. ]]
 210
 211 [[Effects:] [Waits until the queue is not empty and not closed. If the queue is empty and closed throws sync_queue_is_closed. Otherwise pull the element from the queue `q` and moves the pulled element into a shared_ptr.]]
 212
 213 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 214
 215 [[Postcondition:] [`! q.full()`.]]
 216
 217 [[Return type:] [`Q::value_type`.]]
 218
 219 [[Return:] [A shared_ptr containing the pulled element.]]
 220
 221 [[Throws:] [Any exception thrown by the move of `e`. Any exception throw when allocation resources are missing. ]]
 222
 223 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 224
 225 ]
 226
 227 [endsect]
 228 ]
 229 [endsect]
 230
 231 [/////////////////////////////////////]
 232 [section:non_waiting Non-waiting Concurrent Queue Operations]
 233
 234 The ConcurrentQueue concept models a queue with Non-waiting operations.
 235
 236
 237 A type `Q` meets the ConcurrentQueue requirements if is a model of a BasicConcurrentQueue and the following expressions are well-formed and have the specified semantics
 238
 239 * `s = q.try_push_back(e);`
 240 * `s = q.try_push_back(rve);`
 241 * `s = q.try_pull_front(lre);`
 242
 243 where
 244
 245 * `q` denotes a value of type `Q`,
 246 * `e` denotes a value of type `Q::value_type`,
 247 * `s` denotes a value of type `queue_status`,
 248 * `u` denotes a value of type `Q::size_type`,
 249 * `lve` denotes an lvalue reference of type Q::value_type,
 250 * `rve` denotes an rvalue reference of type Q::value_type:
 251 [/* `spe` denotes a shared_ptr<Q::value_type>]
 252
 253
 254 [/////////////////////////////////////]
 255 [section:try_push_back `s = q.try_push_back(e);`]
 256
 257 [variablelist
 258
 259 [[Effects:] [If the queue `q` is not full and not closed, push back the `e` to the queue copying it.]]
 260
 261 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation when the operation succeeds. ]]
 262
 263 [[Return type:] [`queue_op_status`.]]
 264
 265 [[Return:] [
 266
 267 - If the queue is closed, returns `queue_op_status::closed`,
 268
 269 - otherwise if the queue `q` is full return `queue_op_status::full`,
 270
 271 - otherwise return `queue_op_status::success`;
 272 ]]
 273
 274 [[Postcondition:] [If the call returns `queue_op_status::success`, `! q.empty()`.]]
 275
 276 [[Throws:] [If the queue is closed, throws sync_queue_is_closed. Any exception thrown by the copy of `e`.]]
 277
 278 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 279
 280 ]
 281
 282 [endsect]
 283 [/////////////////////////////////////]
 284 [section:try_push_back_m `s = q.try_push_back(rve);`]
 285
 286 [variablelist
 287
 288 [[Effects:] [If the queue `q` is not full and not closed, push back the `e` onto the queue moving it.]]
 289
 290 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 291
 292 [[Return type:] [`queue_op_status`.]]
 293
 294 [[Return:] [
 295
 296 - If the queue is closed, returns `queue_op_status::closed`,
 297
 298 - otherwise if the queue `q` is full return `queue_op_status::full`,
 299
 300 - otherwise return `queue_op_status::success`;
 301 ]]
 302
 303 [[Postcondition:] [If the call returns `queue_op_status::success`, `! q.empty()`.]]
 304
 305 [[Throws:] [ Any exception thrown by the copy of `e`.]]
 306
 307 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 308
 309 ]
 310
 311 [endsect]
 312 [/////////////////////////////////////]
 313 [section:try_pull_front_lv `s = q.try_pull_front(lve)`]
 314
 315 [variablelist
 316
 317 [[Effects:] [If the queue is not empty pulls the element from the queue `q` and moves the pulled element into `lve` (this could need an allocation for unbounded queues).]]
 318
 319 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 320
 321 [[Postcondition:] [`! q.full()`.]]
 322
 323 [[Return type:] [`bool`.]]
 324
 325 [[Return:] [
 326
 327 - If the queue `q` is empty return `queue_op_status::empty`,
 328
 329 - otherwise return `queue_op_status::success`;
 330
 331 ]]
 332
 333 [[Throws:] [Any exception thrown by the move of `e`.]]
 334
 335 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 336
 337 ]
 338
 339 [endsect]
 340 [endsect]
 341 [/////////////////////////////////////]
 342 [section:non_blocking Non-blocking Concurrent Queue Operations]
 343
 344 For cases when blocking for mutual exclusion is undesirable, we have non-blocking operations.
 345 The interface is the same as the try operations but is allowed to also return queue_op_status::busy
 346 in case the operation is unable to complete without blocking.
 347
 348 Non-blocking operations are provided only for lock based queues
 349
 350 * `s = q.nonblocking_push_back(nb, e);`
 351 * `s = q.nonblocking_push_back(nb, rve);`
 352 * `s = q.nonblocking_pull_front(nb, lre);`
 353
 354
 355 where
 356
 357 * `q` denotes a value of type `Q`,
 358 * `e` denotes a value of type Q::value_type,
 359 * `s` denotes a value of type `queue_status`,
 360 * `lve` denotes an lvalue reference of type Q::value_type,
 361 * `rve` denotes an rvalue reference of type Q::value_type:
 362 [/* `spe` denotes a shared_ptr<Q::value_type>]
 363
 364
 365 [/////////////////////////////////////]
 366 [section:nonblocking_push_back `s = q.nonblocking_push_back(e);`]
 367
 368 [variablelist
 369
 370 [[Effects:] [If the queue `q` is not full and not closed, push back the `e` to the queue copying it.]]
 371
 372 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation when the operation succeeds. ]]
 373
 374 [[Return type:] [`queue_op_status`.]]
 375
 376 [[Return:] [
 377
 378 - If the operation would block, return queue_op_status::busy,
 379
 380 - otherwise, if the queue is closed, return `queue_op_status::closed`,
 381
 382 - otherwise, if the queue `q` is full return `queue_op_status::full`,
 383
 384 - otherwise return `queue_op_status::success`;]]
 385
 386 [[Postcondition:] [If the call returns `queue_op_status::success`, `! q.empty()`.]]
 387
 388 [[Throws:] [If the queue is closed, throws sync_queue_is_closed. Any exception thrown by the copy of `e`.]]
 389
 390 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 391
 392 ]
 393
 394 [endsect]
 395 [/////////////////////////////////////]
 396 [section:nonblocking_push_back_m `s = q.nonblocking_push_back(rve);`]
 397
 398 [variablelist
 399
 400 [[Effects:] [If the queue `q` is not full and not closed, push back the `e` onto the queue moving it.]]
 401
 402 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 403
 404 [[Return type:] [`queue_op_status`.]]
 405
 406 [[Return:] [
 407
 408 - If the operation would block, return queue_op_status::busy,
 409
 410 - otherwise if the queue is closed, returns `queue_op_status::closed`,
 411
 412 - otherwise if the queue `q` is full return `queue_op_status::full`,
 413
 414 - otherwise return `queue_op_status::success`;]]
 415
 416 [[Postcondition:] [If the call returns `queue_op_status::success`, `! q.empty()`.]]
 417
 418 [[Throws:] [ Any exception thrown by the copy of `e`.]]
 419
 420 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 421
 422 ]
 423
 424 [endsect]
 425 [/////////////////////////////////////]
 426 [section:nonblocking_pull_front_lv `s = q.nonblocking_pull_front(lve)`]
 427
 428 [variablelist
 429
 430 [[Effects:] [If the queue is not empty pulls the element from the queue `q` and moves the pulled element into `lve` (this could need an allocation for unbounded queues).]]
 431
 432 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 433
 434 [[Postcondition:] [`! q.full()`.]]
 435
 436 [[Return type:] [`bool`.]]
 437
 438 [[Return:] [
 439
 440 - If the operation would block, return queue_op_status::busy,
 441
 442 - otherwise if the queue `q` is empty return `queue_op_status::empty`,
 443
 444 - otherwise return `queue_op_status::success`;]]
 445
 446 [[Throws:] [Any exception thrown by the move of `e`.]]
 447
 448 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 449
 450 ]
 451
 452 [endsect]
 453 [endsect]
 454 [/////////////////////////////////////]
 455 [section:bounded Bounded Concurrent Queue Operations]
 456
 457 Bounded queues add the following valid expressions
 458
 459 * `Q q(u);`
 460 * `b = q.full();`
 461 * `u = q.capacity();`
 462
 463
 464 where
 465
 466 * `q` denotes a value of type `Q`,
 467 * `b` denotes a value of type `bool`,
 468 * `u` denotes a value of type `Q::size_type`,
 469
 470 [/////////////////////////////////////]
 471 [section:full `b = q.full();`]
 472
 473 [variablelist
 474
 475 [[Return type:] [`bool`.]]
 476
 477 [[Return:] [Return `true` iff the queue is full.]]
 478
 479 [[Remark:] [Not all queues will have a full state, and these would always return false if the function is provided.]]
 480
 481 ]
 482
 483 [endsect]
 484
 485 [/////////////////////////////////////]
 486 [section:capacity `b = q.capacity();`]
 487
 488 [variablelist
 489
 490 [[Return type:] [`Q::size_type`.]]
 491
 492 [[Return:] [Return the capacity of queue.]]
 493 ]
 494
 495 [endsect]
 496
 497
 498 [endsect]
 499 [/////////////////////////////////////]
 500 [section:closed_op Closed Concurrent Queue Operations]
 501
 502 Closed queues add the following valid expressions
 503
 504 * `q.close();`
 505 * `b = q.closed();`
 506
 507 * `s = q.wait_push_back(e);`
 508 * `s = q.wait_push_back(rve);`
 509 * `s = q.wait_pull_front(lre);`
 510
 511 [/////////////////////////////////////]
 512 [section:wait_push_back `q.close();`]
 513
 514 [variablelist
 515
 516 [[Effects:] [Close the queue.]]
 517
 518 ]
 519
 520 [endsect]
 521 [/////////////////////////////////////]
 522 [section:wait_push_back `b = q.closed();`]
 523
 524 [variablelist
 525
 526 [[Return type:] [`bool`.]]
 527
 528 [[Return:] [Return `true` iff the queue is closed.]]
 529 ]
 530
 531 [endsect]
 532
 533 [/////////////////////////////////////]
 534 [section:wait_push_back `s = q.wait_push_back(e);`]
 535
 536 [variablelist
 537
 538 [[Effects:] [Waits until the queue is not full (for bounded queues) and then push back `e` to the queue copying it (this could need an allocation for unbounded queues).]]
 539
 540 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 541
 542 [[Postcondition:] [`! q.empty()`.]]
 543
 544 [[Return type:] [`queue_op_status`.]]
 545
 546 [[Return:] [
 547
 548 - If the queue is closed return `queue_op_status::closed`,
 549
 550 - otherwise, return `queue_op_status::success` if no exception is thrown.
 551
 552 ]]
 553
 554 [[Throws:] [Any exception thrown by the copy of `e`.]]
 555
 556 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 557
 558 ]
 559
 560 [endsect]
 561 [/////////////////////////////////////]
 562 [section:wait_push_back_m `s = q.wait_push_back(rve);`]
 563
 564 [variablelist
 565
 566 [[Effects:] [Waits until the queue is not full (for bounded queues) and then push `e` to the queue moving it back in the queue (this could need an allocation for unbounded queues).]]
 567
 568 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 569
 570 [[Postcondition:] [`! q.empty()`.]]
 571
 572 [[Return type:] [`queue_op_status`.]]
 573
 574 [[Return:] [
 575
 576 - If the queue is closed return `queue_op_status::closed`,
 577
 578 - otherwise, return `queue_op_status::success` if no exception is thrown.
 579
 580 .]]
 581
 582 [[Throws:] [Any exception thrown by the copy of `e`.]]
 583
 584 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 585
 586 ]
 587
 588 [endsect]
 589 [/////////////////////////////////////]
 590 [section:wait_pull_front_lv `s = q.wait_pull_front(lve)`]
 591
 592 [variablelist
 593
 594 [[Effects:] [if the queue is not empty and not closed, waits until the queue is not empty and then pull_front the element from the queue `q` and moves the pulled element into `lve`.]]
 595
 596 [[Synchronization:] [Prior pull-like operations on the same object synchronizes with this operation.]]
 597
 598 [[Postcondition:] [`! q.full()`.]]
 599
 600 [[Return type:] [`queue_op_status`.]]
 601
 602 [[Return:] [
 603
 604 - If the queue is empty and closed, return `queue_op_status::closed`,
 605
 606 - otherwise, return `queue_op_status::success` if no exception is thrown.
 607 ]]
 608
 609 [[Throws:] [Any exception thrown by the move of `e`.]]
 610
 611 [[Exception safety:] [If an exception is thrown then the queue state is unmodified.]]
 612
 613 ]
 614
 615 [endsect]
 616
 617 [endsect]
 618
 619 [endsect]
 620
 621 [/////////////////////////////////////]
 622 [section:queue_op_status Queue Operation Status]
 623
 624   #include <boost/thread/concurrent_queues/queue_op_status.hpp>
 625
 626   namespace boost
 627   {
 628      enum class queue_op_status { success = 0, empty, full, closed, busy }
 629   }
 630
 631 [endsect]
 632 [/////////////////////////////////////]
 633 [section:queue_base Queue Base]
 634
 635   #include <boost/thread/concurrent_queues/queue_base.hpp>
 636
 637   namespace boost
 638   {
 639     template <typename ValueType, class SizeType=std::size_t>
 640     class queue_base
 641     {
 642     public:
 643       typedef ValueType value_type;
 644       typedef SizeType size_type;
 645
 646       // Constructors/Assignment/Destructors
 647       virtual ~queue_base() {};
 648
 649       // Observers
 650       virtual bool empty() const = 0;
 651       virtual bool full() const = 0;
 652       virtual size_type size() const = 0;
 653       virtual bool closed() const = 0;
 654
 655       // Modifiers
 656       virtual void close() = 0;
 657
 658       virtual void push_back(const value_type& x) = 0;
 659       virtual void push_back(BOOST_THREAD_RV_REF(value_type) x) = 0;
 660
 661       virtual void pull_front(value_type&) = 0;
 662       virtual value_type pull_front() = 0;
 663
 664       virtual queue_op_status try_push_back(const value_type& x) = 0;
 665       virtual queue_op_status try_push_back(BOOST_THREAD_RV_REF(value_type) x) = 0;
 666       virtual queue_op_status try_pull_front(value_type&) = 0;
 667
 668       virtual queue_op_status nonblocking_push_back(const value_type& x) = 0;
 669       virtual queue_op_status nonblocking_push_back(BOOST_THREAD_RV_REF(value_type) x) = 0;
 670       virtual queue_op_status nonblocking_pull_front(value_type&) = 0;
 671
 672       virtual queue_op_status wait_push_back(const value_type& x) = 0;
 673       virtual queue_op_status wait_push_back(BOOST_THREAD_RV_REF(value_type) x) = 0;
 674       virtual queue_op_status wait_pull_front(value_type& elem) = 0;
 675
 676     };
 677   }
 678
 679 [endsect]
 680 [/////////////////////////////////////]
 681 [section:queue_adaptor Queue Adaptor]
 682
 683   #include <boost/thread/concurrent_queues/queue_adaptor.hpp>
 684
 685   namespace boost
 686   {
 687     template <typename Queue>
 688     class queue_adaptor : public queue_base<typename Queue::value_type, typename Queue::size_type>
 689     {
 690     public:
 691       typedef typename Queue::value_type value_type;
 692       typedef typename Queue::size_type size_type;
 693
 694       // Constructors/Assignment/Destructors
 695
 696       queue_adaptor();
 697
 698       // Observers
 699       bool empty() const;
 700       bool full() const;
 701       size_type size() const { return queue.size(); }
 702       bool closed() const;
 703
 704       // Modifiers
 705       void close();
 706
 707       void push_back(const value_type& x);
 708       void push_back(BOOST_THREAD_RV_REF(value_type) x);
 709
 710       void pull_front(value_type& x);
 711       value_type pull_front();
 712
 713       queue_op_status try_push_back(const value_type& x);
 714       queue_op_status try_push_back(BOOST_THREAD_RV_REF(value_type) x);
 715       queue_op_status try_pull_front(value_type& x);
 716
 717       queue_op_status nonblocking_push_back(const value_type& x);
 718       queue_op_status nonblocking_push_back(BOOST_THREAD_RV_REF(value_type) x);
 719       queue_op_status nonblocking_pull_front(value_type& x);
 720
 721       queue_op_status wait_push_back(const value_type& x);
 722       queue_op_status wait_push_back(BOOST_THREAD_RV_REF(value_type) x);
 723       queue_op_status wait_pull_front(value_type& x);
 724
 725     };
 726   }
 727
 728 [endsect]
 729 [/////////////////////////////////////]
 730 [section:queue_views Queue Views]
 731
 732   #include <boost/thread/concurrent_queues/queue_views.hpp>
 733
 734   namespace boost
 735   {
 736     template <typename Queue>
 737     class queue_back_view;
 738     template <typename Queue>
 739     class queue_front_view
 740
 741     template <class T>
 742     using queue_back = queue_back_view<queue_base<T>>;
 743     template <class T>
 744     using queue_front = queue_front_view<queue_base<T>>;
 745   }
 746
 747 [/////////////////////////////////////]
 748 [section:queue_back_view Class template `queue_back_view<>`]
 749
 750     template <typename Queue>
 751     class queue_back_view
 752     {
 753     public:
 754       typedef typename Queue::value_type value_type;
 755       typedef typename Queue::size_type size_type;
 756
 757       // Constructors/Assignment/Destructors
 758       queue_back_view(Queue& q) noexcept;
 759
 760       // Observers
 761       bool empty() const;
 762       bool full() const;
 763       size_type size() const;
 764       bool closed() const;
 765
 766       // Modifiers
 767       void close();
 768
 769       void push(const value_type& x);
 770       void push(BOOST_THREAD_RV_REF(value_type) x);
 771
 772       queue_op_status try_push(const value_type& x);
 773       queue_op_status try_push(BOOST_THREAD_RV_REF(value_type) x);
 774
 775       queue_op_status nonblocking_push(const value_type& x);
 776       queue_op_status nonblocking_push(BOOST_THREAD_RV_REF(value_type) x);
 777
 778       queue_op_status wait_push(const value_type& x);
 779       queue_op_status wait_push(BOOST_THREAD_RV_REF(value_type) x);
 780
 781     };
 782
 783 [endsect]
 784 [/////////////////////////////////////]
 785 [section:queue_front_view Class template `queue_front_view<>`]
 786
 787
 788     template <typename Queue>
 789     class queue_front_view
 790     {
 791     public:
 792       typedef typename Queue::value_type value_type;
 793       typedef typename Queue::size_type size_type;
 794
 795       // Constructors/Assignment/Destructors
 796       queue_front_view(Queue& q) BOOST_NOEXCEPT;
 797
 798       // Observers
 799       bool empty() const;
 800       bool full() const;
 801       size_type size() const;
 802       bool closed() const;
 803
 804       // Modifiers
 805       void close();
 806
 807       void pull(value_type& x);
 808       value_type pull();
 809
 810       queue_op_status try_pull(value_type& x);
 811
 812       queue_op_status nonblocking_pull(value_type& x);
 813
 814       queue_op_status wait_pull(value_type& x);
 815
 816     };
 817
 818
 819 [endsect]
 820 [endsect]
 821 [/////////////////////////////////////]
 822 [section:sync_bounded_queue_ref Synchronized Bounded Queue]
 823
 824   #include <boost/thread/sync_bounded_queue.hpp>
 825
 826   namespace boost
 827   {
 828     struct sync_queue_is_closed : std::exception {};
 829
 830     template <typename ValueType>
 831     class sync_bounded_queue;
 832
 833     // Stream-like operators
 834     template <typename ValueType>
 835     sync_bounded_queue<ValueType>& operator<<(sync_bounded_queue<ValueType>& sbq, ValueType&& elem);
 836     template <typename ValueType>
 837     sync_bounded_queue<ValueType>& operator<<(sync_bounded_queue<ValueType>& sbq, ValueType const&elem);
 838     template <typename ValueType>
 839     sync_bounded_queue<ValueType>& operator>>(sync_bounded_queue<ValueType>& sbq, ValueType &elem);
 840   }
 841
 842 [/////////////////////////////////////]
 843 [section:sync_queue_is_closed Class `sync_queue_is_closed`]
 844
 845   #include <boost/thread/sync_bounded_queue.hpp>
 846
 847   namespace boost
 848   {
 849     struct sync_queue_is_closed : std::exception {};
 850   }
 851
 852 [endsect]
 853 [/////////////////////////////////////]
 854 [section:sync_bounded_queue Class template `sync_bounded_queue<>`]
 855
 856   #include <boost/thread/sync_bounded_queue.hpp>
 857   namespace boost
 858   {
 859     template <typename ValueType>
 860     class sync_bounded_queue
 861     {
 862     public:
 863       typedef ValueType value_type;
 864       typedef std::size_t size_type;
 865
 866       sync_bounded_queue(sync_bounded_queue const&) = delete;
 867       sync_bounded_queue& operator=(sync_bounded_queue const&) = delete;
 868       explicit sync_bounded_queue(size_type max_elems);
 869       template <typename Range>
 870       sync_bounded_queue(size_type max_elems, Range range);
 871       ~sync_bounded_queue();
 872
 873       // Observers
 874       bool empty() const;
 875       bool full() const;
 876       size_type capacity() const;
 877       size_type size() const;
 878       bool closed() const;
 879
 880       // Modifiers
 881       void push_back(const value_type& x);
 882       void push_back(value_type&& x);
 883
 884       queue_op_status try_push_back(const value_type& x);
 885       queue_op_status try_push_back(value_type&&) x);
 886
 887       queue_op_status nonblocking_push_back(const value_type& x);
 888       queue_op_status nonblocking_push_back(value_type&& x);
 889
 890       void pull_front(value_type&);
 891       value_type pull_front();
 892
 893       queue_op_status try_pull_front(value_type&);
 894       queue_op_status nonblocking_pull_front(value_type&);
 895
 896
 897       void close();
 898     };
 899   }
 900
 901 [/      shared_ptr<ValueType> ptr_pull_front();]
 902
 903 [/////////////////////////////////////]
 904 [section:constructor Constructor `sync_bounded_queue(size_type)`]
 905
 906       explicit sync_bounded_queue(size_type max_elems);
 907
 908 [variablelist
 909
 910 [[Effects:] [Constructs a sync_bounded_queue with a maximum number of elements given by `max_elems`. ]]
 911
 912 [[Throws:] [any exception that can be throw because of resources unavailable. ]]
 913
 914 ]
 915
 916
 917 [endsect]
 918 [/////////////////////////////////////]
 919 [section:constructort Template Constructor `sync_bounded_queue(size_type, Range)`]
 920
 921       template <typename Range>
 922       sync_bounded_queue(size_type max_elems, Range range);
 923
 924 [variablelist
 925
 926 [[Effects:] [Constructs a sync_bounded_queue with a maximum number of elements given by `max_elems` and push back the elements of the range. ]]
 927
 928 [[Throws:] [any exception that can be throw because of resources unavailable. ]]
 929
 930 ]
 931
 932 [endsect]
 933
 934 [endsect]
 935 [/////////////////////////////////////]
 936 [section:stream_out_operators Non-Member Function `operator<<()`]
 937
 938   #include <boost/thread/sync_bounded_queue.hpp>
 939   namespace boost
 940   {
 941     template <typename ValueType>
 942     sync_bounded_queue<ValueType>& operator<<(sync_bounded_queue<ValueType>& sbq, ValueType&& elem);
 943     template <typename ValueType>
 944     sync_bounded_queue<ValueType>& operator<<(sync_bounded_queue<ValueType>& sbq, ValueType const&elem);
 945   }
 946
 947 [endsect]
 948 [/////////////////////////////////////]
 949 [section:stream_in_operators Non-Member Function `operator>>()`]
 950
 951   #include <boost/thread/sync_bounded_queue.hpp>
 952   namespace boost
 953   {
 954     template <typename ValueType>
 955     sync_bounded_queue<ValueType>& operator>>(sync_bounded_queue<ValueType>& sbq, ValueType &elem);
 956   }
 957
 958 [endsect]
 959 [endsect]
 960
 961 [/////////////////////////////////////]
 962 [section:sync_queue_ref Synchronized Unbounded Queue]
 963
 964   #include <boost/thread/sync_queue.hpp>
 965   namespace boost
 966   {
 967     template <typename ValueType>
 968     class sync_queue;
 969
 970     // Stream-like operators
 971     template <typename ValueType>
 972     sync_queue<ValueType>& operator<<(sync_queue<ValueType>& sbq, ValueType&& elem);
 973     template <typename ValueType>
 974     sync_queue<ValueType>& operator<<(sync_queue<ValueType>& sbq, ValueType const&elem);
 975     template <typename ValueType>
 976     sync_queue<ValueType>& operator>>(sync_queue<ValueType>& sbq, ValueType &elem);
 977   }
 978
 979 [/////////////////////////////////////]
 980 [section:sync_queue Class template `sync_queue<>`]
 981
 982   #include <boost/thread/sync_queue.hpp>
 983
 984   namespace boost
 985   {
 986     template <typename ValueType, class Container = csbl::devector<ValueType>>
 987     class sync_queue
 988     {
 989     public:
 990       typedef ValueType value_type;
 991       typedef Container underlying_queue_type;
 992       typedef typename Container::size_type size_type;
 993
 994       sync_queue(sync_queue const&) = delete;
 995       sync_queue& operator=(sync_queue const&) = delete;
 996       sync_queue();
 997       explicit template <typename Range>
 998       sync_queue(Range range); // Not yet implemented
 999       ~sync_queue();
1000
1001       // Observers
1002       bool empty() const;
1003       bool full() const;
1004       size_type size() const;
1005       bool closed() const;
1006
1007       // Modifiers
1008       void push_back(const value_type& x);
1009       void push_back(value_type&& x);
1010
1011       queue_op_status try_push_back(const value_type& x);
1012       queue_op_status try_push_back(value_type&&) x);
1013
1014       queue_op_status nonblocking_push_back(const value_type& x);
1015       queue_op_status nonblocking_push_back(value_type&& x);
1016
1017       void pull_front(value_type&);
1018       value_type pull_front();
1019
1020       queue_op_status try_pull_front(value_type&);
1021       queue_op_status nonblocking_pull_front(value_type&);
1022
1023       underlying_queue_type underlying_queue() noexcept;
1024
1025       void close();
1026     };
1027   }
1028
1029
1030 [/        shared_ptr<ValueType> ptr_pull_front();]
1031
1032
1033 [/////////////////////////////////////]
1034 [section:constructor Constructor `sync_queue(size_type)`]
1035
1036       explicit sync_queue();
1037
1038 [variablelist
1039
1040 [[Effects:] [Constructs an empty sync_queue. ]]
1041
1042 [[Throws:] [any exception that can be throw because of resources unavailable. ]]
1043
1044 ]
1045
1046
1047 [endsect]
1048 [/////////////////////////////////////]
1049 [section:full Member Function `full()`]
1050
1051       bool full() const;
1052
1053 [variablelist
1054
1055 [[Returns:] [false. ]]
1056
1057 ]
1058
1059 [endsect]
1060 [/////////////////////////////////////]
1061 [section:constructor Member Function `underlying_queue()`]
1062
1063       underlying_queue_type underlying_queue() noexcept;
1064
1065 [variablelist
1066
1067 [[Returns:] [Moves internal queue. ]]
1068
1069 ]
1070
1071 [endsect]
1072
1073 [endsect]
1074
1075 [/////////////////////////////////////]
1076 [section:stream_out_operators Non-Member Function `operator<<()`]
1077
1078   #include <boost/thread/sync_queue.hpp>
1079   namespace boost
1080   {
1081     template <typename ValueType>
1082     sync_queue<ValueType>& operator<<(sync_queue<ValueType>& sbq, ValueType&& elem);
1083     template <typename ValueType>
1084     sync_queue<ValueType>& operator<<(sync_queue<ValueType>& sbq, ValueType const&elem);
1085   }
1086
1087 [endsect]
1088 [/////////////////////////////////////]
1089 [section:stream_in_operators Non-Member Function `operator>>()`]
1090
1091   #include <boost/thread/sync_queue.hpp>
1092   namespace boost
1093   {
1094     template <typename ValueType>
1095     sync_queue<ValueType>& operator>>(sync_queue<ValueType>& sbq, ValueType &elem);
1096   }
1097
1098 [endsect]
1099
1100 [endsect]
1101
1102 [endsect]
1103 [endsect]