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

public:
    typedef implementation-defined value_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();
    value_type& value() 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.

value_type& value() const

Returns: Reference to 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_set.h"

int main() {
    using Set = tbb::concurrent_unordered_set<int>;
    Set set = {1, 2, 3};

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

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

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