std::shared_ptr::use_count(3)

💖 NAME 💖

std::shared_ptr::use_count - std::shared_ptr::use_count

okay so bestie, welcome to the std::shared_ptr::use_count(3) page from the C++ Standard Libary manual 💅 (yes, that's literally the manual name — "Libary" and all, no cap). This function is lowkey one of the shared-pointer vibe checks: it tells you how many shared_ptrs are holding hands with the same object 🫶.

✨ Synopsis ✨

long use_count() const noexcept;

It returns the number of different shared_ptr instances (this one included 👑) that are managing the current object. If there's no managed object, 0 is returned.

In a multithreaded environment, the value returned by use_count is approximate — typical implementations use a memory_order_relaxed load. So like, it's giving "estimate" energy, not "absolute truth" energy 😭.

🎀 Parameters 🎀

(none) — zero. nada. no parameters, bestie 🫶

🦋 Return value 🦋

The number of std::shared_ptr instances managing the current object, or 0 if there is no managed object. That's it. That's the whole return value. Slay 💅.

🌸 Notes 🌸

✨ Common use cases include ✨

• comparison with 0 — if use_count returns zero, the shared pointer is empty and manages no objects (whether or not its stored pointer is nullptr). 💀
• comparison with 1 — if use_count returns 1, there are no other owners. The deprecated (since C++17) member function unique() is provided for this use case. (until C++20) In multithreaded environment, this does not imply that the object is safe to modify because accesses to the managed object by former shared owners may not have completed, and because new shared owners may be introduced concurrently, such as by std::weak_ptr::lock.

🎀 Example 🎀

// Run this code

        #include <iostream>
        #include <memory>

        void fun(std::shared_ptr<int> sp)
        {
            std::cout << "in fun(): sp.use_count() == " << sp.use_count()
                      << " (object @ " << sp << ")\n";
        }

        int main()
        {
            auto sp1 = std::make_shared<int>(5);
            std::cout << "in main(): sp1.use_count() == " << sp1.use_count()
                      << " (object @ " << sp1 << ")\n";

            fun(sp1);
        }

💖 Possible output: 💖

        in main(): sp1.use_count() == 1 (object @ 0x20eec30)
        in fun(): sp.use_count() == 2 (object @ 0x20eec30)

🌈 See also 🌈

• unique (until C++20) — checks whether the managed object is managed only by the current shared_ptr object (public member function).

source/version/date vibes: http://cppreference.com · 2024.06.10 · page: std::shared_ptr::use_count(3) 💖✨