# concurrent_queue Template Class

## Summary

Template class for queue with concurrent operations.

## Syntax

    template<typename T, typename Alloc=cache_aligned_allocator<T> > class concurrent_queue;

## Header

    #include "tbb/concurrent_queue.h"

## Description

A `concurrent_queue` is a first-in first-out data structure that permits multiple threads to concurrently push and pop items. Its capacity is unbounded, subject to memory limitations on the target machine.

The interface is similar to STL `std::queue` except where it must differ to make concurrent modification safe.

Differences Between STL queue and Intel(R) 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
`unsafe_size()` | Returns number of items in queue | Returns number of items in queue. May return incorrect value if any `push` or `try_pop` operations are concurrently in flight.
Copy and pop item unless queue q is empty. | bool b=!q.empty(); if(b) { x=q.front(); q.pop(); } | bool b = q.try_pop (x)

## Members

    namespace tbb {
                        template<typename T,
                     typename Alloc=cache_aligned_allocator<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;
                typedef Alloc allocator_type;

                explicit concurrent_queue(const Alloc& a = Alloc ());
                concurrent_queue(const concurrent_queue& src,
                                 const Alloc& a = Alloc());
                template<typename InputIterator>
                concurrent_queue(InputIterator first, InputIterator last,
                                 const Alloc& a = Alloc());
                ~concurrent_queue();

                void push( const T& source );
                bool try_pop T& destination );
                void clear() ;

                size_type unsafe_size() const;
                bool empty() const;
                Alloc get_allocator() const;

                typedef implementation-defined iterator;
                typedef implementation-defined const_iterator;

                // iterators (these are slow and intended only for debugging)
                iterator unsafe_begin();
                iterator unsafe_end();
                const_iterator unsafe_begin() const;
                const_iterator unsafe_end() const;
            };
        }

In Intel® Threading Building Blocks (Intel® TBB) 2.1, a `concurrent_queue` could be bounded. Intel® TBB 2.2 moves this functionality to `concurrent_bounded_queue`. Compile with `TBB_DEPRECATED=1` to restore the old functionality, or (recommended) use `concurrent_bounded_queue` instead.

The following table provides additional information on the members of this template class.
Member | Description
--- | ---
concurrent_queue( const Alloc& a = Alloc () ) | Constructs empty queue.
concurrent_queue( const concurrent_queue& src, const Alloc& a = Alloc() ) | Constructs a copy of src.
template<typename InputIterator> concurrent_queue( InputIterator first, InputIterator last, const Alloc& a = Alloc() ) | Constructs a queue containing copies of elements in the iterator half-open interval [first,last).
~concurrent_queue() | Destroys all items in the queue.
void push( const T& source ) | Pushes a copy of `source` onto back of the queue.
bool try_pop ( T& destination ) | If value is available, pops it from the queue, assigns it to destination, and destroys the original value. Otherwise does nothing. Returns: True if value was popped; false otherwise. ### Note `try_pop` was called `pop_if_present` in Intel® TBB 2.1. Compile with `TBB_DEPRECATED=1` to use the old name.
void clear() | Clears the queue. Afterwards `size()==0`.
size_type unsafe_size() const | Returns Number of items in the queue. If there are concurrent modifications in flight, the value might not reflect the actual number of items in the queue.
bool empty() const | Returns: `true` if queue has no items; false otherwise.
Alloc get_allocator() const | Returns: Copy of allocator used to construct the queue.

## Iterators

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);
        typedef concurrent_queue<int>::iterator iter;
        for(iter i(queue.unsafe_begin()); i!=queue.unsafe_end(); ++i)
            cout << *i << " ";
        cout << endl;
        return 0;

    }

The following table provides additional information on the members of this template class.
Member | Description
--- | ---
iterator unsafe_begin() | Returns: `iterator` pointing to beginning of the queue.
iterator unsafe_end() | Returns: `iterator` pointing to end of the queue.
const_iterator unsafe_begin() const | Returns: `const_iterator` with pointing to beginning of the queue.
`const_iterator` unsafe_end() const | Returns: `const_iterator` pointing to end of the queue.

Parent topic: Containers Overview