Node Handle

Summary

Node handle (supported since C++11) is a move only type, used to transfer nodes between node-based containers (TBB concurrent unordered containers) without performing copy/move operations. Transfer can be performed only between containers with the same key_type, value_type and allocator_type, ignoring hasher and key_equal.

Generic type of node handle is unspecified, but each node-based container exposes the corresponding type as the member node_type.

Node handle allows reading and modifying the element stored in the owned node.

Default constructed and moved-from node handles are empty (does not own any node). Non-empty node handle destroys and deallocates the owned node during the destruction using the copy of the container allocator, stored in each node handle.

Members of node handle

public:
    typedef implementation-defined key_type;
    typedef implementation-defined mapped_type;
    typedef implementation-defined allocator_type;

    node_type();
    node_type(node_type&& nh);

    node_type& operator=(node_type&& nh);
    explicit operator bool() const;

    ~node_type();

    allocator_type get_allocator() const;
    bool empty();
    key_type& key() const;
    mapped_type& mapped() const;
    void swap(node_type& nh);
Node handle members
Member Description
node_type()

Constructs an empty node handle.

node_type(node_type&& nh)

Takes ownership of the node from nh and leave it in empty state.

node_type& operator=(node_type&& nh)

If *this is not empty, destroys and deallocates the owned node. In either case, takes ownership of the node from nh and leave it in empty state.

Returns: A reference to *this.

~node_type()

If *this is not empty, destroys and deallocates the owned node.

bool empty()

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

explicit operator bool() const

Converts to !nh.empty().

allocator_type get_allocator() const;

Returns: Copy of the stored allocator instance. The behavior is undefined if node handle is empty.

key_type& key() const

Returns: Reference to the key of the element stored in the owned node. The behavior is undefined if node handle is empty.

mapped_type& mapped() const

Returns: Reference to the value of the element stored in the owned node. The behavior is undefined if node handle is empty.

void swap(node_type& nh)

Swaps ownership of container nodes.

Node handle usage example

#include "tbb/concurrent_unordered_map.h"

int main() {
    using Map = tbb::concurrent_unordered_map<int, int>;
    Map map = {{1, 1}, {2, 2}, {3, 3}};

    // Extract an element from the container
    Map::node_type nh = map.unsafe_extract(2);

    // Change key/value of handled element
    nh.key() = 7;
    nh.mapped() = 9;

    // Insert an element to the new container
    Map map2;
    map2.insert(std::move(nh));
}
For more complete information about compiler optimizations, see our Optimization Notice.