[For complete, up-to-date TBB information visit: http://www.ThreadingBuildingBlocks.org]
Summary
Template class for queue with concurrent operations.
Syntax
template<typename T> class concurrent_queue;
Header
#include "tbb/concurrent_queue.h"
Description
A concurrent_queue is a bounded first-in first-out data structure that permits multiple threads to concurrently push and pop items. The default bounds are large enough to make the queue practically unbounded, subject to memory limitations on the target machine.
The interface is different than for an STL std::queue because concurrent_queue is designed for concurrent operations.
Table 16: Differences Between STL queue and Intel® Threading Building Blocks concurrent_queue
Feature
STL std::queue
concurrent_queue
Access to front and back
Methods front and back
Not present. They would be unsafe while concurrent operations are in progress.
size_type
unsigned integral type
signed integral type
size()
Returns number of items in queue
Returns number of pushes minus the number of pops. Waiting push or pop operations are included in the difference. The size() is negative if there are pops waiting for corresponding pushes.
Copy and pop item from queue q.
x=q.front(); q.pop()
q.pop(x)
Copy and pop item unless queue q is empty.
bool b=!q.empty();
if(b) {
x=q.front();
q.pop();
}
bool b = q.pop_if_present(x)
pop of empty queue
not allowed
waits until item becomes available
CAUTION: If the push or pop operations block, they block using user-space locks, which can waste processor resources when the blocking time is long. Class concurrent_queue is designed for situations where the blocking time is typically short relative to the rest of the application time.
Members
namespace tbb {
template<typename T>
class concurrent_queue {
public:
// types
typedef T value_type;
typedef T& reference;
typedef const T& const_reference;
typedef std::ptrdiff_t size_type;
typedef std::ptrdiff_t difference_type;
concurrent_queue() {}
~concurrent_queue();
void push( const T& source );
void pop( T& destination );
bool pop_if_present( T& destination );
size_type size() const {return internal_size();}
bool empty() const;
size_t capacity() const;
void set_capacity( size_type capacity );
typedef implementation-defined iterator;
typedef implementation-defined const_iterator;
// iterators (these are slow an intended only for debugging)
iterator begin();
iterator end();
const_iterator begin() const;
const_iterator end() const;
};
}
Effects
Construct empty queue.
Effects
Destroy all items in the queue.
Effects
Wait until size()<capacity, and then push copy of source onto back of the queue.
Effects
Wait until a value becomes available and pop it from the queue. Assign it to destination. Destroy the original value.
Effects
If value is available, pop it from the queue, assign it to destination, and destroy the original value. Otherwise do nothing.
Returns
True if value was popped; false otherwise.
Returns
Number pushes minus number of pops. The result is negative if there are pop operations waiting for corresponding pushes.
Returns
size()==0
Returns
Maximum number of values that the queue can hold.
Effects
Set the maximum number of values that the queue can hold.
A concurrent_queue provides limited iterator support that is intended solely to allow programmers to inspect a queue during debugging. It provides iterator and const_iterator types. Both follow the usual STL conventions for forward iterators. The iteration order is from least recently pushed to most recently pushed. Modifying a concurrent_queue invalidates any iterators that reference it.
CAUTION: The iterators are relatively slow. They should be used only for debugging.
Example
The following program builds a queue with the integers 0..9, and then dumps the queue to standard output. Its overall effect is to print 0 1 2 3 4 5 6 7 8 9.
#include "tbb/concurrent_queue.h"
#include <iostream>
using namespace std;
using namespace tbb;
int main() {
concurrent_queue<int> queue;
for( int i=0; i<10; ++i )
queue.push(i);
for( concurrent_queue<int>::const_iterator i(queue.begin()); i!=queue.end(); ++i )
cout << *i << " ";
cout << endl;
return 0;
}
4.2.10.1 iterator begin()
Returns
iterator pointing to beginning of the queue.
4.2.10.2 iterator end()
Returns
iterator pointing to end of the queue.
4.2.10.3 const_iterator begin() const
Returns
const_iterator with pointing to beginning of the queue.
4.2.10.4 const_iterator end() const
Returns
const_iterator pointing to end of the queue.
[For complete, up-to-date TBB information visit: http://www.ThreadingBuildingBlocks.org]