.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

===================
concurrent_hash_map
===================
**[containers.concurrent_hash_map]**

``concurrent_hash_map`` is a class template for an unordered associative container
that holds key-value pairs with unique keys and supports concurrent insertion, lookup, and erasure.

Class Template Synopsis
-----------------------

   .. code:: cpp

      // Defined in header <oneapi/tbb/concurrent_hash_map.h>

      namespace oneapi {
          namespace tbb {

             template <typename Key, typename T,
                       typename HashCompare = tbb_hash_compare<Key>,
                       typename Allocator = tbb_allocator<std::pair<const Key, T>>>
             class concurrent_hash_map {
             public:
                   using key_type = Key;
                   using mapped_type = T;
                   using value_type = std::pair<const Key, T>;

                   using reference = value_type&;
                   using const_reference = const value_type&;
                   using pointer = typename std::allocator_traits<Allocator>::pointer;
                   using const_pointer = typename std::allocator_traits<Allocator>::const_pointer;

                   using hash_compare_type = HashCompare;
                   using allocator_type = Allocator;

                   using size_type = <implementation-defined unsigned integer type>;
                   using difference_type = <implementation-defined signed integer type>;

                   using iterator = <implementation-defined ForwardIterator>;
                   using const_iterator = <implementation-defined constant ForwardIterator>;

                   using range_type = <implementation-defined ContainerRange>;
                   using const_range_type = <implementation-defined constant ContainerRange>;

                   class accessor;
                   class const_accessor;

                   // Construction, destruction, copying
                   concurrent_hash_map();

                   explicit concurrent_hash_map( const hash_compare_type& compare,
                                                 const allocator_type& alloc = allocator_type() );

                   explicit concurrent_hash_map( const allocator_type& alloc );

                   concurrent_hash_map( size_type n, const hash_compare_type& compare,
                                        const allocator_type& alloc = allocator_type() );

                   concurrent_hash_map( size_type n, const allocator_type& alloc = allocator_type() );

                   template <typename InputIterator>
                   concurrent_hash_map( InputIterator first, InputIterator last,
                                        const hash_compare_type& compare,
                                        const allocator_type& alloc = allocator_type() );

                   template <typename InputIterator>
                   concurrent_hash_map( InputIterator first, InputIterator last,
                                        const allocator_type& alloc = allocator_type() );

                   concurrent_hash_map( std::initializer_list<value_type> init,
                                        const hash_compare_type& compare = hash_compare_type(),
                                        const allocator_type& alloc = allocator_type() );

                   concurrent_hash_map( std::initializer_list<value_type> init,
                                        const allocator_type& alloc );

                   concurrent_hash_map( const concurrent_hash_map& other );
                   concurrent_hash_map( const concurrent_hash_map& other,
                                        const allocator_type& alloc );

                   concurrent_hash_map( concurrent_hash_map&& other );
                   concurrent_hash_map( concurrent_hash_map&& other,
                                        const allocator_type& alloc );

                   ~concurrent_hash_map();

                   concurrent_hash_map& operator=( const concurrent_hash_map& other );
                   concurrent_hash_map& operator=( concurrent_hash_map&& other );
                   concurrent_hash_map& operator=( std::initializer_list<value_type> init );

                   allocator_type get_allocator() const;

                   // Concurrently unsafe modifiers
                   void clear();

                   void swap( concurrent_hash_map& other );

                   // Hash policy
                   void rehash( size_type sz = 0 );
                   size_type bucket_count() const;

                   // Size and capacity
                   size_type size() const;
                   bool empty() const;
                   size_type max_size() const;

                   // Lookup
                   bool find( const_accessor& result, const key_type& key ) const;
                   bool find( accessor& result, const key_type& key );

                   template <typename K>
                   bool find( const_accessor& result, const K& key ) const;

                   template <typename K>
                   bool find( accessor& result, const K& key );

                   size_type count( const key_type& key ) const;

                   template <typename K>
                   size_type count( const K& key ) const;

                   // Modifiers
                   bool insert( const_accessor& result, const key_type& key );
                   bool insert( accessor& result, const key_type& key );

                   template <typename K>
                   bool insert( const_accessor& result, const K& key );

                   template <typename K>
                   bool insert( accessor& result, const K& key );

                   bool insert( const_accessor& result, const value_type& value );
                   bool insert( accessor& result, const value_type& value );
                   bool insert( const_accessor& result, value_type&& value );
                   bool insert( accessor& result, value_type&& value );

                   bool insert( const value_type& value );
                   bool insert( value_type&& value );

                   template <typename InputIterator>
                   void insert( InputIterator first, InputIterator last );

                   void insert( std::initializer_list<value_type> init );

                   template <typename... Args>
                   bool emplace( const_accessor& result, Args&&... args );

                   template <typename... Args>
                   bool emplace( accessor& result, Args&&... args );

                   template <typename... Args>
                   bool emplace( Args&&... args );

                   bool erase( const key_type& key );

                   template <typename K>
                   bool erase( const K& key );

                   bool erase( const_accessor& item_accessor );
                   bool erase( accessor& item_accessor );

                   // Iterators
                   iterator begin();
                   const_iterator begin() const;
                   const_iterator cbegin() const;

                   iterator end();
                   const_iterator end() const;
                   const_iterator cend() const;

                   std::pair<iterator, iterator> equal_range( const key_type& key );
                   std::pair<const_iterator, const_iterator> equal_range( const key_type& key ) const;

                   template <typename K>
                   std::pair<iterator, iterator> equal_range( const K& key );

                   template <typename K>
                   std::pair<const_iterator, const_iterator> equal_range( const K& key ) const;

                   // Parallel iteration
                   range_type range( std::size_t grainsize = 1 );
                   const_range_type range( std::size_t grainsize = 1 ) const;
             }; // class concurrent_hash_map

          } // namespace tbb
      } // namespace oneapi

Requirements:

* The expression ``std::allocator_type<Allocator>::destroy(m, val)``, where ``m`` is an object
  of the type ``Allocator`` and ``val`` is an object of type ``value_type``, must be well-formed.
  Member functions can impose stricter requirements depending on the type of the operation.
* The type ``HashCompare`` must meet the :doc:`HashCompare requirements <../named_requirements/containers/hash_compare>`.
* The type ``Allocator`` must meet the ``Allocator`` requirements from the [allocator.requirements] ISO C++ Standard section.


Member classes
--------------

.. toctree::
    :maxdepth: 1

    concurrent_hash_map_cls/accessors.rst

Member functions
----------------

.. toctree::
    :maxdepth: 1

    concurrent_hash_map_cls/construct_destroy_copy.rst
    concurrent_hash_map_cls/unsafe_modifiers.rst
    concurrent_hash_map_cls/hash_policy.rst
    concurrent_hash_map_cls/size_and_capacity.rst
    concurrent_hash_map_cls/lookup.rst
    concurrent_hash_map_cls/modifiers.rst
    concurrent_hash_map_cls/iterators.rst
    concurrent_hash_map_cls/parallel_iteration.rst

Non-member functions
--------------------

These functions provide binary comparison and swap operations on ``oneapi::tbb::concurrent_hash_map``
objects.

The exact namespace where these functions are defined is unspecified, as long as they may be used in
respective comparison operations. For example, an implementation may define the classes and functions
in the same internal namespace and define ``oneapi::tbb::concurrent_hash_map`` as a type alias for which
the non-member functions are reachable only via argument-dependent lookup.

.. code:: cpp

   template <typename Key, typename T, typename HashCompare, typename Allocator>
   bool operator==( const concurrent_hash_map<Key, T, HashCompare, Allocator>& lhs,
                    const concurrent_hash_map<Key, T, HashCompare, Allocator>& rhs );

   template <typename Key, typename T, typename HashCompare, typename Allocator>
   bool operator!=( const concurrent_hash_map<Key, T, HashCompare, Allocator>& lhs,
                    const concurrent_hash_map<Key, T, HashCompare, Allocator>& rhs );

   template <typename Key, typename T, typename HashCompare, typename Allocator>
   void swap( concurrent_hash_map<Key, T, HashCompare, Allocator>& lhs,
              concurrent_hash_map<Key, T, HashCompare, Allocator>& rhs );

.. toctree::
    :maxdepth: 1

    concurrent_hash_map_cls/non_member_swap.rst
    concurrent_hash_map_cls/non_member_binary_comparisons.rst

Other
-----

.. toctree::
    :maxdepth: 1

    concurrent_hash_map_cls/deduction_guides.rst