Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/memory/new/set new handler"

From cppreference.com
< cpp‎ | memory‎ | new
(Remove gender from sentence)
m ({{c}}, fmt)
 
Line 2: Line 2:
 
{{cpp/memory/new/navbar}}
 
{{cpp/memory/new/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl header | new}}
+
{{dcl header|new}}
 
{{dcl rev multi|until1=c++11
 
{{dcl rev multi|until1=c++11
 
|dcl1=
 
|dcl1=
Line 11: Line 11:
 
{{dcl end}}
 
{{dcl end}}
  
−
Makes {{tt|new_p}} the new global new-handler function and returns the previously installed new-handler.
+
Makes {{c|new_p}} the new global new-handler function and returns the previously installed new-handler.
  
 
The ''new-handler'' function is the function called by {{rlp|operator_new|allocation functions}} whenever a memory allocation attempt fails. Its intended purpose is one of three things:
 
The ''new-handler'' function is the function called by {{rlp|operator_new|allocation functions}} whenever a memory allocation attempt fails. Its intended purpose is one of three things:
  
−
@1@ make more memory available
+
@1@ make more memory available,
  
−
@2@ terminate the program (e.g. by calling {{lc|std::terminate}})
+
@2@ terminate the program (e.g. by calling {{lc|std::terminate}}),
  
 
@3@ throw exception of type {{lc|std::bad_alloc}} or derived from {{lc|std::bad_alloc}}.
 
@3@ throw exception of type {{lc|std::bad_alloc}} or derived from {{lc|std::bad_alloc}}.
Line 33: Line 33:
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | new_p | pointer to function of type {{lc|std::new_handler}}, or null pointer}}
+
{{par|new_p|pointer to function of type {{lc|std::new_handler}}, or null pointer}}
 
{{par end}}
 
{{par end}}
  
Line 41: Line 41:
 
===Example===
 
===Example===
 
{{example
 
{{example
−
|
+
|code=
−
| code=
+
 
#include <iostream>
 
#include <iostream>
 
#include <new>
 
#include <new>
Line 55: Line 54:
 
{
 
{
 
     std::set_new_handler(handler);
 
     std::set_new_handler(handler);
−
     try {
+
     try
−
         while (true) {
+
    {
 +
         while (true)
 +
        {
 
             new int[1000'000'000ul]();
 
             new int[1000'000'000ul]();
 
         }
 
         }
−
     } catch (const std::bad_alloc& e) {
+
     }
 +
    catch (const std::bad_alloc& e)
 +
    {
 
         std::cout << e.what() << '\n';
 
         std::cout << e.what() << '\n';
 
     }
 
     }
 
}
 
}
−
| p=true
+
|p=true
−
| output=
+
|output=
 
Memory allocation failed, terminating
 
Memory allocation failed, terminating
 
std::bad_alloc
 
std::bad_alloc
Line 71: Line 74:
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/memory/new/dsc operator_new}}
+
{{dsc inc|cpp/memory/new/dsc operator_new}}
−
{{dsc inc | cpp/memory/new/dsc get_new_handler}}
+
{{dsc inc|cpp/memory/new/dsc get_new_handler}}
−
{{dsc inc | cpp/memory/new/dsc new_handler}}
+
{{dsc inc|cpp/memory/new/dsc new_handler}}
−
{{dsc inc | cpp/memory/new/dsc bad_alloc}}
+
{{dsc inc|cpp/memory/new/dsc bad_alloc}}
 
{{dsc end}}
 
{{dsc end}}
  
 
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
 
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 09:30, 14 June 2023

 
C++
 
Utilities library
General utilities
Relational operators (deprecated in C++20)
 
Dynamic memory management
Uninitialized memory algorithms
Constrained uninitialized memory algorithms
Allocators
Garbage collection support
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)



 
Low level memory management
 
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)

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 their 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)

Contents

[edit] Parameters

new_p - pointer to function of type std::new_handler, or null pointer

[edit] Return value

The previously-installed new handler, or a null pointer value if none was installed.

[edit] 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

[edit] See also

 allocation functions
(function) [edit]
(C++11)
 obtains the current new handler
(function) [edit]
function pointer type of the new handler
(typedef) [edit]
exception thrown when memory allocation fails
(class) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/memory/new/set_new_handler&oldid=153365"