_set_new_handler (Windows CE 5.0)

Article
09/14/2012

Developing an Application > Microsoft C Run-time Library for Windows CE > Run-time Library Reference

Transfer control to your error-handling mechanism if the new operator fails to allocate memory.

_PNH _set_new_handler(
  _PNH pNewHandler);

Parameters

pNewHandler
Pointer to the application-supplied memory handling function

Return Values

_set_new_handler returns a pointer to the previous exception handling function registered by _set_new_handler, so that the previous function can be restored later. If no previous function has been set, the return value may be used to restore the default behavior; this value may be NULL.

Remarks

These functions are supported by all versions of the C run-time libraries.

Call the _set_new_handler function to specify an exception-handling function that is to gain control if the new operator fails to allocate memory.

If new fails, the run-time system calls the exception-handling function that was passed as an argument to _set_new_handler. _PNH, defined in NEW.H, is a 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.

_set_new_handler is essentially a garbage-collection scheme. The run-time system retries allocation each time your function returns a nonzero value and fails if your function returns 0.

The following code example show how the _set_new_handler function registers the specified exception-handling function 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 reinstate it later:

_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_mode function sets the new handler mode for malloc. The new handler mode indicates whether, on failure, malloc is to call the new handler routine as set by _set_new_handler.

By default, malloc does not call the new handler routine on failure to allocate memory. You can override this default behavior so that, when malloc fails to allocate memory, malloc calls the new handler routine in the same way that the new operator does when it fails for the same reason.

To override the default, call

_set_new_mode(1)

early in your program, or link with NEWMODE.OBJ.

Example

Description

This program uses _set_new_handler to print an error message if the new operator fails.

Code

#include <stdlib.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;
}

// Output
Allocation failed %0 bytes not available.

Requirements

OS Versions: Windows CE 2.0 and later.

Header: new.h.

Link Library: coredll.dll.