Transfer control to your error-handling mechanism if the new operator fails to allocate memory.
#include <new.h>
_PNH _set_new_handler( _PNH pNewHandler );
_PNH _set_nnew_handler( _PNH pNewHandler );
_PNH _set_fnew_handler( _PNH pNewHandler );
_PNHH _set_hnew_handler( _PNHH pNewHandler );
_PNHB _set_bnew_handler( _PNHB pNewHandler );
| pNewHandler | Pointer to a function that you write |
Use the C++ _set_new_handler function to gain control if the new operator fails to allocate memory. The run-time system automatically calls _set_new_handler when new fails.
To use _set_new_handler, you must write an exception-handling function and then pass it as an argument to _set_new_handler. To facilitate the easy declaration of this new handler, three pointer-to-function types—_PNH, _PNHH, and _PNHB—are defined in NEW.H and described in the following table:
| Type | Description |
| _PNH | Pointer to a function that returns type int and takes an argument of type size_t. Use size_t to specify the amount of space to be allocated. |
| _PNHH | Pointer to a function that returns type int and takes two arguments—the type unsigned long and the type size_t arguments specified to the huge new operator. |
| _PNHB | Pointer to a function that returns type int and takes two arguments—the type __segment and the type size_t arguments specified to the based new operator. Your function must ensure the correct binding of the segment variable to its return value. |
Basically, _set_new_handler is a garbage collection scheme. The run-time system retries allocation each time your function returns a nonzero value and fails new if your function returns 0.
An occurrence of one of the _set_new_handler functions in a program registers the exception-handling function specified in the argument list with the run-time system:
#include <new.h>
int handle_program_memory_depletion( size_t )
{
// Your code
}
void main( void )
{
_set_new_handler( handle_program_memory_depletion );
int *pi = new int[BIG_NUMBER];
}
You can save the function address that was last passed to the _set_new_handler function and then reinstate it at a later time:
_PNH old_handler = _set_new_handler( my_handler );
// Code that requires my_handler
_set_new_handler( old_handler )
// Code that requires old_handler
The _set_new_handler function is defined in five different forms that allow you to manage the heap for five different memory models:
| Prototype | Purpose |
| _PNH _set_new_handler( _PNH ); | Default new handler |
| _PNH _set_nnew_handler( _PNH ); | Manages the near heap |
| _PNH _set_fnew_handler( _PNH ); | Manages the far heap |
| _PNHH _set_hnew_handler( _PNHH ); | Manages the huge heap |
| _PNHB _set_bnew_handler( _PNHB ); | Manages based heaps |
The _set_new_handler function automatically maps to either the _set_nnew_handler or the _set_fnew_handler function, depending on the default data model.
If the default memory model is either small or medium, you can call _set_fnew_handler to manage the far heap. If the default memory model is either compact or large, you can call _set_nnew_handler to manage the near heap.
You can explicitly call the _set_hnew_handler and the _set_bnew_handler functions to manage both the huge and based heaps.
In a multithreaded environment, handlers are maintained separately for each process and thread. Each new process lacks installed handlers. Each new thread gets a copy of its parent thread's new handlers. Thus, each process and thread is in charge of its own free-store error handling.
The _set_new_handler function returns a pointer to the allocated program memory if successful. It returns a 0 if it's unsuccessful.
_set_new_handler
Standards:None
16-Bit:DOS, WIN, WIN DLL
32-Bit:DOS32X
_set_bnew_handler, _set_fnew_handler, _set_hnew_handler, _set_nnew_handler
Standards:None
16-Bit:DOS, WIN, WIN DLL
32-Bit:None
_bfreeseg, _bheapseg, calloc, delete, free, malloc, new, realloc
For more information on the new and delete operators, see Chapter 5 of the C++ Language Reference (in the Microsoft C/C++ version 7.0 documentation set).
/* HANDLER.CPP: This program uses _set_new_handler to print an
* error message if the new operator fails.
*/
#include <stdio.h>
#include <new.h>
/* Allocate memory in chunks of size MemBlock. */
const size_t MemBlock = 1024;
/* Allocate a memory block for the printf function to use in case
* of memory allocation failure; the printf function uses malloc.
* The failsafe memory block must be visible globally because the
* handle_program_memory_depletion function can take one
* argument only.
*/
char * failsafe = new char[128];
/* Declare a customized function to handle memory-allocation failure.
* Pass this function as an argument to _set_new_handler.
*/
int handle_program_memory_depletion( size_t );
void main( void )
{
// Register existence of a new memory handler.
_set_new_handler( handle_program_memory_depletion );
size_t *pmemdump = new size_t[MemBlock];
for( ; pmemdump != 0; pmemdump = new size_t[MemBlock] );
}
int handle_program_memory_depletion( size_t size )
{
// Release character buffer memory.
delete failsafe;
printf( "Allocation failed, " );
printf( "%u bytes not available.\n", size );
// Tell new to stop allocation attempts.
return 0;
}