bslstl_ownerhash

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Use of @ref owner_hash

Purpose

Provide an ownership hash functor for shared and weak pointers.

Classes

• bsl::owner_hash: owner hash functor for shared_ptr and weak_ptr

Canonical header: bsl_memory.h

See also

bslstl_sharedptr

Description

This component provides the C++26 standard functor, bsl::owner_hash, that calculates the hash of a smart pointer object by the address of their bslma::SharedPtrRep data. Note that this class is an empty POD type.

Usage

This section illustrates intended use of this component.

Example 1: Basic Use of @ref owner_hash

Suppose we need an unordered map accepting shared pointers as keys. We also expect that this container will be accessible from multiple threads and some of them will store weak versions of smart pointers to break reference cycles.

First, we define an owner-based equality predicate, that is required by the bsl::unordered_map along with this owner-based hash.

struct TestOwnerEqual {
    // TYPES
    typedef void is_transparent;
 
    template <class T1, class T2>
    bool operator()(const bsl::shared_ptr<T1>& lhs,
                    const bsl::shared_ptr<T2>& rhs) const
        // For the specified 'lhs' and 'rhs', return the result of
        // 'lhs.owner_equal(rhs)'
    {
        return lhs.owner_equal(rhs);
    }
 
    template <class T1, class T2>
    bool operator()(const bsl::shared_ptr<T1>& lhs,
                    const bsl::weak_ptr<T2>&   rhs) const
        // For the specified 'lhs' and 'rhs', return the result of
        // 'lhs.owner_equal(rhs)'
    {
        return lhs.owner_equal(rhs);
    }
 
    template <class T1, class T2>
    bool operator()(const bsl::weak_ptr<T1>&   lhs,
                    const bsl::shared_ptr<T2>& rhs) const
        // For the specified 'lhs' and 'rhs', return the result of
        // 'lhs.owner_equal(rhs)'
    {
        return lhs.owner_equal(rhs);
    }
 
    template <class T1, class T2>
    bool operator()(const bsl::weak_ptr<T1>& lhs,
                    const bsl::weak_ptr<T2>& rhs) const
        // For the specified 'lhs' and 'rhs', return the result of
        // 'lhs.owner_equal(rhs)'
    {
        return lhs.owner_equal(rhs);
    }
};

Note that this struct is defined only to avoid cycle dependencies between BDE components. In real code for these purposes it is recommended to use bsl::owner_equal.

Then, we create a container and populate it:

    typedef bsl::unordered_map<
        bsl::shared_ptr<int>,
        int,
        bsl::owner_hash,
        TestOwnerEqual> Map;
 
    Map                  container;
 
    bsl::shared_ptr<int> sharedPtr1 = bsl::make_shared<int>(1);
    bsl::shared_ptr<int> sharedPtr2 = bsl::make_shared<int>(2);
    bsl::weak_ptr<int>   weakPtr1(sharedPtr1);
 
    container[sharedPtr1] = 1;
    container[sharedPtr2] = 2;

Now, we make sure, that shared pointers can be used to perform lookup:

    Map::const_iterator iter = container.find(sharedPtr1);
    assert(container.end() != iter        );
    assert(1               == iter->second);
 
    iter = container.find(sharedPtr2);
    assert(container.end() != iter);
    assert(2               == iter->second);

Finally, we simulate the situation of accessing the container from another thread and perform lookup using weak pointers:

    iter = container.find(weakPtr1);
    assert(container.end() != iter        );
    assert(1               == iter->second);
 
    bsl::weak_ptr<int> weakPtr3(bsl::make_shared<int>(3));
    iter = container.find(weakPtr3);
    assert(container.end() == iter);