std::set_new_handler

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Utilities library

Type support (basic types, RTTI, type traits)

Dynamic memory management

Error handling

Program utilities

Variadic functions

Date and time

Function objects

initializer_list (C++11)

bitset

hash (C++11)

Relational operators

rel_ops::operator!=rel_ops::operator>rel_ops::operator<=rel_ops::operator>=

Optional and any

optional (C++17)

any (C++17)

Pairs and tuples

pair

tuple (C++11)

apply (C++17)

piecewise_construct_t (C++11)

piecewise_construct (C++11)

integer_sequence (C++14)

Swap, forward and move

swap

exchange (C++14)

forward (C++11)

move (C++11)

move_if_noexcept (C++11)

Type operations

declval (C++11)

as_const (C++17)

 

Dynamic memory management

Smart pointers unique_ptr (C++11) shared_ptr (C++11) weak_ptr (C++11) auto_ptr (until C++17) owner_less (C++11) enable_shared_from_this (C++11) bad_weak_ptr (C++11) default_delete (C++11) Allocators allocator allocator_traits (C++11) allocator_arg_t (C++11) allocator_arg (C++11) uses_allocator (C++11) scoped_allocator_adaptor (C++11) pmr::polymorphic_allocator (C++17) Memory resources pmr::memory_resource (C++17) pmr::get_default_resource (C++17) pmr::set_default_resource (C++17) pmr::new_delete_resource (C++17) pmr::null_memory_resource (C++17) pmr::synchronized_pool_resource (C++17) pmr::unsynchronized_pool_resource (C++17) pmr::monotonic_buffer_resource (C++17) pmr::pool_options (C++17)

Uninitialized storage uninitialized_copy uninitialized_copy_n (C++11) uninitialized_fill uninitialized_fill_n raw_storage_iterator get_temporary_buffer return_temporary_buffer Garbage collection support declare_reachable (C++11) undeclare_reachable (C++11) declare_no_pointers (C++11) undeclare_no_pointers (C++11) pointer_safety (C++11) get_pointer_safety (C++11) Miscellaneous pointer_traits (C++11) addressof (C++11) align (C++11) C Library malloc calloc realloc free Low level memory management

 

Low level memory management

Functions

operator newoperator new[]

operator deleteoperator delete[]

get_new_handler (C++11)

set_new_handler

Classes

bad_alloc

bad_array_new_length (C++11)

nothrow_t

Types

new_handler

Objects

nothrow

 

Defined in header <new>
std::new_handler set_new_handler( std::new_handler new_p );

Makes new_p the new global new-handler function and returns the previously installed new-handler.

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 his own new-handler, which may offer behavior different than the default one.

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.

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)

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.

Exceptions

(none)	(until C++11)
noexcept specification:   noexcept	(since C++11)

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[100000000ul];
        }
    } catch (const std::bad_alloc& e) {
        std::cout << e.what() << '\n';
    }
}

Output:

Memory allocation failed, terminating
std::bad_alloc

See also

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