std::set_new_handler(3)

🎀 NAME 🎀

std::set_new_handler — okay bestie, you've landed on the C++ Standard Libary page, manual section (3) (yes, the header spells it like that — I don't make the rules 😭). This is the function that swaps in the global new-handler, and it's giving main-character memory management 🫶.

✨ Synopsis ✨

Defined in header <new>:

std::new_handler set_new_handler( std::new_handler new_p ) throw();

(until C++11)

std::new_handler set_new_handler( std::new_handler new_p ) noexcept;

(since C++11)

Okay so what it does: it makes new_p the new global new-handler function and returns the previously installed new-handler. Swap, return, slay ✨.

The new-handler function is the function called by allocation functions whenever a memory allocation attempt fails. Its intended purpose is one of three things:

1. make more memory available,
2. terminate the program (e.g. by calling std::terminate),
3. throw exception of type std::bad_alloc or derived from std::bad_alloc.

The default implementation throws std::bad_alloc. The user can install their own new-handler, which may offer behavior different than the default one. Customization era, fr fr 💙.

If new-handler returns, the allocation function repeats the previously-failed allocation attempt and calls the new-handler again if the allocation fails again. To end the loop, new-handler may call std::set_new_handler(nullptr): if, after a failed allocation attempt, allocation function finds that std::get_new_handler returns a null pointer value, it will throw std::bad_alloc. Loop danger, but make it fashion 💀.

At program startup, new-handler is a null pointer.

This function is thread-safe. Every call to std::set_new_handler synchronizes-with (see std::memory_order) the subsequent std::set_new_handler and std::get_new_handler calls (since C++11). Thread-safe queen behavior, iykyk 💅.

🌸 Parameters 🌸

• new_p — pointer to function of type std::new_handler, or null pointer.

🦋 Return value 🦋

The previously-installed new handler, or a null pointer value if none was installed. Yes, it remembers the old one for you 💜.

🌈 Example 🌈

// Run this code

#include <iostream>
#include <new>

void handler()
{
    std::cout << "Memory allocation failed, terminating\n";
    std::set_new_handler(nullptr);
}

int main()
{
    std::set_new_handler(handler);
    try
    {
        while (true)
        {
            new int[1000'000'000ul]();
        }
    }
    catch (const std::bad_alloc& e)
    {
        std::cout << e.what() << '\n';
    }
}

🍓 Possible output 🍓

Memory allocation failed, terminating
std::bad_alloc

👑 See also 👑

• operator new — allocation functions
• operator new[] — (function)
• get_new_handler — obtains the current new handler (C++11) (function)
• new_handler — function pointer type of the new handler (typedef)
• bad_alloc — exception thrown when memory allocation fails (class)

---

This page is from cppreference.com, dated 2024.06.10 — go handle your new-handlers and stay hydrated, bestie 💖✨