# concurrent_priority_queue Template Class

## Summary

Template class for priority queue with concurrent operations.

## Syntax

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

## Header

    #include "tbb/concurrent_priority_queue.h"

## Description

A `concurrent_priority_queue` is a container that permits multiple threads to concurrently push and pop items. Items are popped in priority order as determined by a template parameter. The capacity of the queue is unbounded, subject to memory limitations on the target machine.

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

Differences Between STL queue and Intel(R) Threading Building Blocks concurrent_priority_queue
Feature | STL std::priority_queue | concurrent_priority_queue
--- | --- | ---
Choice of underlying container | Sequence template parameter | No choice of underlying container; allocator choice is provided instead
Access to highest priority item | `const value_type& top() const` | Not available. Unsafe for concurrent container
Copy and pop item if present | `bool b=!q.empty(); if(b) { x=q.top(); q.pop(); }` | `bool b = q.try_pop(x);`
Get number of items in queue | `size_type size() const` | Same, but may be inaccurate due to pending concurrent push or pop operations
Check if there are items in queue | `bool empty() const` | Same, but may be inaccurate due to pending concurrent push or pop operations

## Members

    namespace tbb {
      template <typename T, typename Compare=std::less<T>,
                typename A=cache_aligned_allocator<T> >
      class concurrent_priority_queue {
        typedef T value_type;
        typedef T& reference;
        typedef const T& const_reference;
        typedef size_t size_type;
        typedef ptrdiff_t difference_type;
        typedef A allocator_type;

        concurrent_priority_queue(const allocator_type& a =
          allocator_type());
        concurrent_priority_queue(size_type init_capacity,
          const allocator_type& a = allocator_type());
        template<typename InputIterator>
        concurrent_priority_queue(InputIterator begin,
          InputIterator end, const allocator_type& a =
          allocator_type());
        concurrent_priority_queue(const
          concurrent_priority_queue& src, const
          allocator_type& a = allocator_type());
        concurrent_priority_queue& operator=(const
          concurrent_priority_queue& src);
        ~concurrent_priority_queue();

        bool empty() const;
        size_type size() const;
        void push(const_reference elem);
        bool try_pop(reference elem);
        void clear();
        void swap(concurrent_priority_queue& other);
        allocator_type get_allocator() const;
      };
    }

### Note

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_priority_queue(const allocator_type& a = allocator_type()) | Constructs empty queue.
concurrent_priority_queue(size_type init_capacity, const allocator_type& a = allocator_type()) | Constructs an empty queue with an initial capacity.
concurrent_priority_queue(InputIterator begin, InputIterator end, const allocator_type& a = allocator_type()) | Constructs a queue containing copies of elements in the iterator half-open interval `[begin, end)`.
concurrent_priority_queue (const concurrent_priority_queue& src, const allocator_type& a = allocator_type()) | Constructs a copy of `src`. This operation is not thread-safe and may result in an error or an invalid copy of `src` if another thread is concurrently modifying `src.`
concurrent_priority_queue& operator=(const concurrent_priority_queue& src) | Assign contents of `src` to `*this`. This operation is not thread-safe and may result in an error or an invalid copy of `src` if another thread is concurrently modifying `src`.
~concurrent_priority_queue() | Destroys all items in the queue, and the container itself, so that it can no longer be used.
bool empty() const | Returns: `true` if queue has no items; `false` otherwise. May be inaccurate when concurrent `push` or `try_pop` operations are pending. This operation reads shared data and may trigger a race condition in race detection tools when used concurrently.
size_type size() const | Returns: Number of items in the queue. May be inaccurate when concurrent `push` or `try_pop` operations are pending. This operation reads shared data and may trigger a race condition in race detection tools when used concurrently.
void push(const_reference elem) | Pushes a copy of `elem` into the queue. This operation is thread-safe with other `push` and `try_pop` operations.
bool try_pop(reference elem) | If the queue is not empty, copies the highest priority item from the queue and assigns it to `elem`, and destroys the popped item in the queue; otherwise, does nothing. This operation is thread-safe with other `push` and `try_pop` operations. Returns: `true` if an item was popped; `false` otherwise.
void clear() | Clears the queue; results in `size()==0`. This operation is not thread-safe.
void swap(concurrent_priority_queue& other) | Swaps the queue contents with those of other. This operation is not thread-safe.
allocator_type get_allocator() const | Returns: Copy of allocator used to construct the queue.

Parent topic: Containers Overview