Align interface of concurrent_queue and concurrent_bounded_queue with concurrent_priority_queue (#396)

* Align interface of concurrent_queue and concurrent_bounded_queue with
concurrent_priority_queue

- added :
  - `operator=` with overloads
  - `assign` method
  - `swap`
  - `operator==`
  - `operator!=`
 - `std::initializer_list` constructor


Signed-off-by: Anton Potapov <[email protected]>
Co-authored-by: kboyarinov <[email protected]>

Author: anton-potapov

source/elements/oneTBB/source/containers/concurrent_bounded_queue_cls.rst

@@ -45,6 +45,9 @@ Class Template Synopsis
                 concurrent_bounded_queue( InputIterator first, InputIterator last,
                                           const allocator_type& alloc = allocator_type() );
 
+                concurrent_bounded_queue( std::initializer_list<value_type> init,
+                                          const allocator_type& alloc = allocator_type() );
+
                 concurrent_bounded_queue( const concurrent_bounded_queue& other );
                 concurrent_bounded_queue( const concurrent_bounded_queue& other,
                                           const allocator_type& alloc );
@@ -55,6 +58,17 @@ Class Template Synopsis
 
                 ~concurrent_bounded_queue();
 
+                concurrent_bounded_queue& operator=( const concurrent_bounded_queue& other );
+                concurrent_bounded_queue& operator=( concurrent_bounded_queue&& other );
+                concurrent_bounded_queue& operator=( std::initializer_list<value_type> init );
+
+                template <typename InputIterator>
+                void assign( InputIterator first, InputIterator last );
+
+                void assign( std::initializer_list<value_type> init );
+
+                void swap( concurrent_bounded_queue& other );
+                
                 allocator_type get_allocator() const;
 
                 void push( const value_type& value );
@@ -113,6 +127,37 @@ Member functions
     concurrent_bounded_queue_cls/unsafe_member_functions.rst
     concurrent_bounded_queue_cls/iterators.rst
 
+Non-member functions
+--------------------
+
+These functions provides binary comparison and swap operations on ``oneapi::tbb::concurrent_bounded_queue``
+objects.
+
+The exact namespace where this function is defined is unspecified, as long as it may be used in
+respective operation. For example, an implementation may define the classes and functions
+in the same internal namespace and define ``oneapi::tbb::concurrent_bounded_queue`` as a type alias for which
+the non-member functions are reachable only via argument-dependent lookup.
+
+.. code:: cpp
+
+    template <typename T, typename Allocator>
+    void swap( concurrent_bounded_queue<T, Allocator>& lhs,
+               concurrent_bounded_queue<T, Allocator>& rhs );
+
+    template <typename T, typename Allocator>
+    bool operator==( const concurrent_bounded_queue<T, Allocator>& lhs,
+                     const concurrent_bounded_queue<T, Allocator>& rhs );
+
+    template <typename T, typename Allocator>
+    bool operator!=( const concurrent_bounded_queue<T, Allocator>& lhs,
+                     const concurrent_bounded_queue<T, Allocator>& rhs );  
+
+.. toctree::
+    :maxdepth: 1
+
+    concurrent_bounded_queue_cls/non_member_swap.rst
+    concurrent_bounded_queue_cls/non_member_binary_comparisons.rst
+    
 Other
 -----
 

source/elements/oneTBB/source/containers/concurrent_bounded_queue_cls/construct_destroy_copy.rst

@@ -18,7 +18,7 @@ Empty container constructors
     Constructs an empty ``concurrent_bounded_queue`` with an unbounded capacity.
     If provided, uses the allocator ``alloc`` to allocate the memory.
 
-Constructor from the sequence of elements
+Constructors from the sequence of elements
 ------------------------------------------
 
     .. code:: cpp
@@ -33,6 +33,13 @@ Constructor from the sequence of elements
     **Requirements**: the type ``InputIterator`` must meet the `InputIterator` requirements from the
     ``[input.iterators]`` ISO C++ Standard section.
 
+    .. code:: cpp
+
+        concurrent_bounded_queue( std::initializer_list<value_type> init,
+                                  const allocator_type& alloc = allocator_type() );
+
+    Equivalent to ``concurrent_bounded_queue(init.begin(), init.end(), alloc)``.
+
 Copying constructors
 --------------------
 
@@ -79,3 +86,65 @@ Destructor
     deallocates the used storage.
 
     The behavior is undefined in case of concurrent operations with ``*this``.
+
+Assignment operators
+--------------------
+
+    .. code:: cpp
+
+        concurrent_bounded_queue& operator=( const concurrent_bounded_queue& other );
+
+    Replaces all elements in ``*this`` by the copies of the elements in ``other``.
+
+    Copy-assigns allocators if ``std::allocator_traits<allocator_type>::propagate_on_container_copy_assignment::value``
+    is ``true``.
+
+    The behavior is undefined in case of concurrent operations with ``*this`` and ``other``.
+
+    **Returns**: a reference to ``*this``.
+
+    .. code:: cpp
+
+        concurrent_bounded_queue& operator=( concurrent_bounded_queue&& other );
+
+    Replaces all elements in ``*this`` by the elements in  ``other`` using move semantics.
+
+    ``other`` is left in a valid, but unspecified state.
+
+    Move-assigns allocators if ``std::allocator_traits<allocator_type>::propagate_on_container_move_assignment::value``
+    is ``true``.
+
+    The behavior is undefined in case of concurrent operations with ``*this`` and ``other``.
+
+    **Returns**: a reference to ``*this``.
+
+    .. code:: cpp
+
+        concurrent_bounded_queue& operator=( std::initializer_list<value_type> init );
+
+    Replaces all elements in ``*this`` by the elements in ``init``.
+
+    The behavior is undefined in case of concurrent operations with ``*this``.
+
+    **Returns**: a reference to ``*this``.
+
+assign
+------
+
+    .. code:: cpp
+
+        template <typename InputIterator>
+        void assign( InputIterator first, InputIterator last );
+
+    Replaces all elements in ``*this`` be the elements in the half-open interval ``[first, last)``.
+
+    The behavior is undefined in case of concurrent operations with ``*this``.
+
+    **Requirements**: the type ``InputIterator`` must meet the `InputIterator` requirements from the
+    ``[input.iterators]`` ISO C++ Standard section.
+
+    .. code:: cpp
+
+        void assign( std::initializer_list<value_type> init );
+
+    Equivalent to ``assign(init.begin(), init.end())``.

source/elements/oneTBB/source/containers/concurrent_bounded_queue_cls/non_member_binary_comparisons.rst

@@ -0,0 +1,28 @@
+.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+=============================
+Non-member binary comparisons
+=============================
+
+.. code:: cpp
+  
+    template <typename T, typename Allocator>
+    bool operator==( const concurrent_bounded_queue<T, Allocator>& lhs,
+                     const concurrent_bounded_queue<T, Allocator>& rhs );
+          
+Checks if ``lhs`` is equal to ``rhs``, that is they have the same number of elements and ``lhs``
+contains all elements from ``rhs``.
+
+**Returns**: ``true`` if ``lhs`` is equal to ``rhs``; ``false``, otherwise.
+
+.. code:: cpp
+
+    template <typename T, typename Allocator>
+    bool operator!=( const concurrent_bounded_queue<T, Allocator>& lhs,
+                     const concurrent_bounded_queue<T, Allocator>& rhs );
+
+Equivalent to ``!(lhs == rhs)``.
+
+**Returns**: ``true`` if ``lhs`` is not equal to ``rhs``; ``false``, otherwise.

source/elements/oneTBB/source/containers/concurrent_bounded_queue_cls/non_member_swap.rst

@@ -0,0 +1,15 @@
+.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+===============
+Non-member swap
+===============
+
+.. code:: cpp
+
+    template <typename T, typename Allocator>
+    void swap( concurrent_bounded_queue<T, Allocator>& lhs,
+               concurrent_bounded_queue<T, Allocator>& rhs );
+
+Equivalent to ``lhs.swap(rhs)``.

source/elements/oneTBB/source/containers/concurrent_bounded_queue_cls/unsafe_member_functions.rst

@@ -34,3 +34,16 @@ clear
         void clear();
 
     Removes all elements from the container.
+
+swap
+----
+
+    .. code:: cpp
+
+        void swap( concurrent_bounded_queue& other );
+
+    Swaps contents of ``*this`` and ``other``.
+
+    Swaps allocators if ``std::allocator_traits<allocator_type>::propagate_on_container_swap::value`` is ``true``.
+
+    Otherwise if ``get_allocator() != other.get_allocator()`` the behavior is undefined.

source/elements/oneTBB/source/containers/concurrent_queue_cls.rst

@@ -45,6 +45,9 @@ Class Template Synopsis
                 concurrent_queue( InputIterator first, InputIterator last,
                                   const allocator_type& alloc = allocator_type() );
 
+                concurrent_queue( std::initializer_list<value_type> init,
+                                  const allocator_type& alloc = allocator_type() );
+
                 concurrent_queue( const concurrent_queue& other );
                 concurrent_queue( const concurrent_queue& other, const allocator_type& alloc );
 
@@ -53,6 +56,17 @@ Class Template Synopsis
 
                 ~concurrent_queue();
 
+                concurrent_queue& operator=( const concurrent_queue& other );
+                concurrent_queue& operator=( concurrent_queue&& other );
+                concurrent_queue& operator=( std::initializer_list<value_type> init );
+
+                template <typename InputIterator>
+                void assign( InputIterator first, InputIterator last );
+
+                void assign( std::initializer_list<value_type> init );
+
+                void swap( concurrent_queue& other );
+
                 void push( const value_type& value );
                 void push( value_type&& value );
 
@@ -97,6 +111,37 @@ Member functions
     concurrent_queue_cls/unsafe_member_functions.rst
     concurrent_queue_cls/iterators.rst
 
+Non-member functions
+--------------------
+
+These functions provides binary comparison and swap operations on ``oneapi::tbb::concurrent_queue``
+objects.
+
+The exact namespace where this function is defined is unspecified, as long as it may be used in
+respective operation. For example, an implementation may define the classes and functions
+in the same internal namespace and define ``oneapi::tbb::concurrent_queue`` as a type alias for which
+the non-member functions are reachable only via argument-dependent lookup.
+
+.. code:: cpp
+
+    template <typename T, typename Allocator>
+    void swap( concurrent_queue<T, Allocator>& lhs,
+               concurrent_queue<T, Allocator>& rhs );
+
+    template <typename T, typename Allocator>
+    bool operator==( const concurrent_queue<T, Allocator>& lhs,
+                     const concurrent_queue<T, Allocator>& rhs );
+
+    template <typename T, typename Allocator>
+    bool operator!=( const concurrent_queue<T, Allocator>& lhs,
+                     const concurrent_queue<T, Allocator>& rhs );  
+
+.. toctree::
+    :maxdepth: 1
+
+    concurrent_queue_cls/non_member_swap.rst
+    concurrent_queue_cls/non_member_binary_comparisons.rst
+
 Other
 -----
 

source/elements/oneTBB/source/containers/concurrent_queue_cls/construct_destroy_copy.rst

@@ -18,7 +18,7 @@ Empty container constructors
     Constructs an empty ``concurrent_queue``. If provided, uses the allocator ``alloc`` to
     allocate the memory.
 
-Constructor from the sequence of elements
+Constructors from the sequence of elements
 ------------------------------------------
 
     .. code:: cpp
@@ -33,6 +33,13 @@ Constructor from the sequence of elements
     **Requirements**: the type ``InputIterator`` must meet the `InputIterator` requirements from the
     ``[input.iterators]`` ISO C++ Standard section.
 
+    .. code:: cpp
+
+        concurrent_queue( std::initializer_list<value_type> init,
+                          const allocator_type& alloc = allocator_type() );
+
+    Equivalent to ``concurrent_queue(init.begin(), init.end(), alloc)``.
+
 Copying constructors
 --------------------
 
@@ -68,6 +75,7 @@ Moving constructors
 
     The behavior is undefined in case of concurrent operations with ``other``.
 
+
 Destructor
 ----------
 
@@ -79,3 +87,65 @@ Destructor
     deallocates the used storage.
 
     The behavior is undefined in case of concurrent operations with ``*this``.
+
+Assignment operators
+--------------------
+
+    .. code:: cpp
+
+        concurrent_queue& operator=( const concurrent_queue& other );
+
+    Replaces all elements in ``*this`` by the copies of the elements in ``other``.
+
+    Copy-assigns allocators if ``std::allocator_traits<allocator_type>::propagate_on_container_copy_assignment::value``
+    is ``true``.
+
+    The behavior is undefined in case of concurrent operations with ``*this`` and ``other``.
+
+    **Returns**: a reference to ``*this``.
+
+    .. code:: cpp
+
+        concurrent_queue& operator=( concurrent_queue&& other );
+
+    Replaces all elements in ``*this`` by the elements in  ``other`` using move semantics.
+
+    ``other`` is left in a valid, but unspecified state.
+
+    Move-assigns allocators if ``std::allocator_traits<allocator_type>::propagate_on_container_move_assignment::value``
+    is ``true``.
+
+    The behavior is undefined in case of concurrent operations with ``*this`` and ``other``.
+
+    **Returns**: a reference to ``*this``.
+
+    .. code:: cpp
+
+        concurrent_queue& operator=( std::initializer_list<value_type> init );
+
+    Replaces all elements in ``*this`` by the elements in ``init``.
+
+    The behavior is undefined in case of concurrent operations with ``*this``.
+
+    **Returns**: a reference to ``*this``.
+
+assign
+------
+
+    .. code:: cpp
+
+        template <typename InputIterator>
+        void assign( InputIterator first, InputIterator last );
+
+    Replaces all elements in ``*this`` be the elements in the half-open interval ``[first, last)``.
+
+    The behavior is undefined in case of concurrent operations with ``*this``.
+
+    **Requirements**: the type ``InputIterator`` must meet the `InputIterator` requirements from the
+    ``[input.iterators]`` ISO C++ Standard section.
+
+    .. code:: cpp
+
+        void assign( std::initializer_list<value_type> init );
+
+    Equivalent to ``assign(init.begin(), init.end())``.