std::declare_reachable(3)

🦋 std::declare_reachable 🦋

okay so this is the std::declare_reachable(3) page from the C++ Standard Libary manual — and yes, the manual name up top really says “Libary,” I’m not fixing it, bestie 😌. This whole page is about one little function that tells the runtime “hey, keep this object alive.”

🌸 NAME 🌸

std::declare_reachable — std::declare_reachable. That’s it. That’s the name. The manpage said it twice and honestly? Repetition is a vibe. Periodt. 💅

✨ Synopsis ✨

Defined in header <memory>
void declare_reachable( void* p );  (since C++11)
                                    (removed in C++23)

So it’s giving “since C++11” and “removed in C++23” — glow-up era, then departure era, no cap 😭.

Now the actual tea: declares the object referenced by the pointer p reachable. Reachable objects will not be deleted by the garbage collector or considered to be a leak by a leak detector even if all pointers to it are destroyed.

An object may be declared reachable multiple times, in which case multiple calls to std::undeclare_reachable would be needed to remove this property. For example, a XOR linked list needs to declare its nodes reachable if the implementation has garbage collection enabled.

bestie, the whole point is keeping stuff alive even when every pointer to it is gone — the garbage collector and the leak detector are looking at it like “nope, not touching that.” 🫶

🎀 Parameters 🎀

• p — a safely-derived pointer or a null pointer.

💫 Return value 💫

(none) — literally no return value, it’s giving “I did the thing and I’m not gonna report back” energy. 💀

😭 Exceptions 😭

May throw std::bad_alloc if the system cannot allocate memory required to track reachable objects.

So if the system can’t allocate the memory it needs to track reachable objects, boom: std::bad_alloc. Keep that in mind, bestie. 🍓

👀 See also 👀

• std::undeclare_reachable — declares that an object can be recycled (C++11) (function template) (removed in C++23).

source/version: http://cppreference.com · date 2024.06.10 · page std::declare_reachable(3) 💖