A.4 C++ dynamic memory allocation functions

The following 5 functions are available as replacements for existing C++ library functions, but the replacements in `mpatrol.h' will only be used if the MP_NOCPLUSPLUS preprocessor macro is not defined. The replacement operators make use of the preprocessor in order to obtain source-level information. If this causes problems then you should define the MP_NONEWDELETE preprocessor macro and use the MP_NEW, MP_NEW_NOTHROW and MP_DELETE macros instead of new and delete directly. To use these C++ features you must include `mpatrol.h' before all other header files, although on UNIX and Windows platforms (and AmigaOS when using gcc) they will be used anyway, albeit with slightly less tracing information.

void *operator new(size_t size)

Allocates size uninitialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to size bytes in length. If size is `0' then the memory allocated will be implicitly rounded up to `1' byte. If there is not enough space in the heap then either the std::bad_alloc exception will be thrown or the null pointer will be returned and errno will be set to ENOMEM --- the behaviour depends on whether the nothrow version of the operator is used. The allocated memory must be deallocated with operator delete.

void *operator new[](size_t size)

Allocates size uninitialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to size bytes in length. If size is `0' then the memory allocated will be implicitly rounded up to `1' byte. If there is not enough space in the heap then either the std::bad_alloc exception will be thrown or the null pointer will be returned and errno will be set to ENOMEM --- the behaviour depends on whether the nothrow version of the operator is used. The allocated memory must be deallocated with operator delete[].

void operator delete(void *ptr)

Frees the memory allocation beginning at ptr so the memory can be reused by another call to allocate memory. If ptr is `NULL' then no memory will be freed. All of the previous contents will be destroyed. This function must only be used with memory allocated by operator new.

void operator delete[](void *ptr)

Frees the memory allocation beginning at ptr so the memory can be reused by another call to allocate memory. If ptr is `NULL' then no memory will be freed. All of the previous contents will be destroyed. This function must only be used with memory allocated by operator new[].

std::new_handler std::set_new_handler(std::new_handler func)

Installs a low-memory handler specifically for use with operator new and operator new[] and returns a pointer to the previously installed handler, or the null pointer if no handler had been previously installed. This will be called repeatedly by both functions when they would normally return `NULL', and this loop will continue until they manage to allocate the requested space. Note that this function is equivalent to __mp_nomemory() and will replace the handler installed by that function.