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

============
Node handles
============
**[containers.node_handles]**

Concurrent associative containers (``concurrent_map``, ``concurrent_multimap``, ``concurrent_set``, ``concurrent_multiset``,
``concurrent_unordered_map``, ``concurrent_unordered_multimap``, ``concurrent_unordered_set``,
and ``concurrent_unordered_multiset``) store elements in individually allocated, connected nodes.
These containers support data transfer between containers with compatible node types by changing the connections
without copying or moving the actual data.

Class synopsis
--------------

.. code:: cpp

    class node-handle { // Exposition-only name
    public:
        using key_type = <container-specific>;    // Only for maps
        using mapped_type = <container-specific>; // Only for maps
        using value_type = <container-specific>;  // Only for sets
        using allocator_type = <container-specific>;

        node-handle();
        node-handle( node-handle&& other );

        ~node-handle();

        node-handle& operator=( node-handle&& other );

        void swap( node-handle& nh );

        bool empty() const;
        explicit operator bool() const;

        key_type& key() const;       // Only for maps
        mapped_type& mapped() const; // Only for maps
        value_type& value() const;   // Only for sets

        allocator_type get_allocator() const;
    };

A ``node handle`` is a container-specific move-only nested type (exposed as `container::node_type`) that
represents a node outside of any container instance. It allows reading and modifying the data stored in the node,
and inserting the node into a compatible container instance. The following containers have compatible node types and
may exchange nodes:

* ``concurrent_map`` and ``concurrent_multimap`` with the same ``key_type``, ``mapped_type`` and
  ``allocator_type``.
* ``concurrent_set`` and ``concurrent_multiset`` with the same ``value_type`` and ``allocator_type``.
* ``concurrent_unordered_map`` and ``concurrent_unordered_multimap`` with the same ``key_type``, ``mapped_type`` and
  ``allocator_type``.
* ``concurrent_unordered_set`` and ``concurrent_unordered_multiset`` with the same ``value_type`` and ``allocator_type``.

Default or moved-from node handles are `empty` and do not represent a valid node.
A non-empty node handle is typically created when a node is extracted out of a container, for example, with the ``unsafe_extract``
method. It stores the node along with a copy of the container's allocator.
Upon assignment or destruction a non-empty node handle destroys the stored data and deallocates the node.

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

Constructors
~~~~~~~~~~~~

    .. code:: cpp

        node-handle();

    Constructs an empty node handle.

-----------------------------------------------------------------------------

    .. code:: cpp

        node-handle( node-handle&& other );

    Constructs a node handle that takes ownership of the node from ``other``.

    ``other`` is left in an empty state.

Assignment
~~~~~~~~~~

    .. code:: cpp

        node-handle& operator=( node-handle&& other );

    Transfers ownership of the node from ``other`` to ``*this``.
    If ``*this`` was not empty before transferring, destroys and deallocates the stored node.

    Move assigns the stored allocator if ``std::allocator_traits<allocator_type>::propagate_on_container_move_assignment::value``
    is ``true``.

    ``other`` is left in an empty state.

Destructor
~~~~~~~~~~

    .. code:: cpp

        ~node-handle();

    Destroys the node handle. If it is not empty, destroys and deallocates the owned node.

Swap
~~~~

    .. code:: cpp

        void swap( node-handle& other )

    Exchanges the nodes owned by ``*this`` and ``other``.

    Swaps the stored allocators if ``std::allocator_traits<allocator_type>::propagate_on_container_swap::value`` is ``true``.

State
~~~~~

    .. code:: cpp

        bool empty() const;

    **Returns**: ``true`` if the node handle is empty, ``false`` otherwise.

-----------------------------------------------------------------------------

    .. code:: cpp

        explicit operator bool() const;

    Equivalent to ``!empty()``.

Access to the stored element
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    .. code:: cpp

        key_type& key() const;

    Available only for map node handles.

    **Returns**: a reference to the key of the element stored in the owned node.

    The behavior is undefined if the node handle is empty.

-----------------------------------------------------------------------------

    .. code:: cpp

        mapped_type& mapped() const;

    Available only for map node handles.

    **Returns**: a reference to the value of the element stored in the owned node.

    The behavior is undefined if the node handle is empty.

-----------------------------------------------------------------------------

    .. code:: cpp

        value_type& value() const;

    Available only for set node handles.

    **Returns**: a reference to the element stored in the owned node.

    The behavior is undefined if the node handle is empty.

get_allocator
~~~~~~~~~~~~~

    .. code:: cpp

        allocator_type get_allocator() const;

    **Returns**: a copy of the allocator stored in the node handle.

    The behavior is undefined if the node handle is empty.