Difference between revisions of "cpp/memory/new/set new handler"
From cppreference.com
m (Text replace - "{{noexcept" to "{{unreviewed noexcept") |
Andreas Krug (Talk | contribs) m ({{c}}, fmt) |
||
| (4 intermediate revisions by 4 users not shown) | |||
| Line 2: | Line 2: | ||
{{cpp/memory/new/navbar}} | {{cpp/memory/new/navbar}} | ||
{{dcl begin}} | {{dcl begin}} | ||
| − | {{dcl header | new}} | + | {{dcl header|new}} |
| − | {{dcl | | | + | {{dcl rev multi|until1=c++11 |
| − | std::new_handler set_new_handler( std::new_handler new_p ); | + | |dcl1= |
| + | std::new_handler set_new_handler( std::new_handler new_p ) throw(); | ||
| + | |dcl2= | ||
| + | std::new_handler set_new_handler( std::new_handler new_p ) noexcept; | ||
}} | }} | ||
{{dcl end}} | {{dcl end}} | ||
| − | Makes {{ | + | 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}}. | ||
| − | The default implementation throws {{lc|std::bad_alloc}}. The user can install | + | The default implementation throws {{lc|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 {{c|std::set_new_handler(nullptr)}}: if, after a failed allocation attempt, allocation function finds that {{lc|std::get_new_handler}} returns a null pointer value, it will throw {{lc|std::bad_alloc}}. | 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 {{c|std::set_new_handler(nullptr)}}: if, after a failed allocation attempt, allocation function finds that {{lc|std::get_new_handler}} returns a null pointer value, it will throw {{lc|std::bad_alloc}}. | ||
| Line 24: | Line 27: | ||
At program startup, ''new-handler'' is a null pointer. | At program startup, ''new-handler'' is a null pointer. | ||
| − | {{ | + | {{rrev|since=c++11| |
| − | + | ||
This function is thread-safe. Every call to {{tt|std::set_new_handler}} ''synchronizes-with'' (see {{lc|std::memory_order}}) the subsequent {{tt|std::set_new_handler}} and {{lc|std::get_new_handler}} calls. | This function is thread-safe. Every call to {{tt|std::set_new_handler}} ''synchronizes-with'' (see {{lc|std::memory_order}}) the subsequent {{tt|std::set_new_handler}} and {{lc|std::get_new_handler}} calls. | ||
}} | }} | ||
| − | |||
===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}} | ||
===Return value=== | ===Return value=== | ||
The previously-installed new handler, or a null pointer value if none was installed. | The previously-installed new handler, or a null pointer value if none was installed. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===Example=== | ===Example=== | ||
{{example | {{example | ||
| − | + | |code= | |
| − | + | ||
#include <iostream> | #include <iostream> | ||
#include <new> | #include <new> | ||
| Line 60: | Line 54: | ||
{ | { | ||
std::set_new_handler(handler); | std::set_new_handler(handler); | ||
| − | try { | + | try |
| − | while (true) { | + | { |
| − | new int[ | + | while (true) |
| + | { | ||
| + | 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 | |
| + | |output= | ||
Memory allocation failed, terminating | Memory allocation failed, terminating | ||
std::bad_alloc | std::bad_alloc | ||
| Line 75: | 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}} | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
Latest revision as of 09:30, 14 June 2023
| 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),
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 |
(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) | |
| (C++11) |
obtains the current new handler (function) |
| function pointer type of the new handler (typedef) | |
| exception thrown when memory allocation fails (class) |
