The <new>
header declares types and functions related to dynamic memory-management. Refer to Chapter 12 for more information about the new
and delete
expressions. Most programs do not need to use <new>
. The header is typically used by libraries and programs that implement their own new
and delete
operators or otherwise provide custom management of dynamic memory.
Most programs do not call the operators directly, but instead use new
and delete
expressions, and the compiler generates calls the appropriate operators. Library implementors sometimes make direct calls to the operators, especially to allocate uninitialized memory. (See <memory>
earlier in this chapter for examples.)
Some specialized applications might implement the global new and delete operators, or provide additional overloaded operators for specialized circumstances, such as allocating memory that is shared across process boundaries. Example 13-35 shows a trivial implementation of the global new
and delete
operators.
Example 13-35: Implementing new and delete with malloc and free.
#include <cstdlib> #include <new> void* operator new(std::size_t size) throw(std::bad_alloc) { void* ptr = malloc(size); if (ptr == 0) throw std::bad_alloc(); return ptr; } void* operator new(std::size_t size, const std::nothrow_t&) throw() { return malloc(size); } void* operator new[](std::size_t size) throw(std::bad_alloc) { return operator new(size); } void* operator new[](std::size_t size, const std::nothrow_t&) throw() { return operator new(size, std::nothrow); } void operator delete(void* ptr) throw() { free(ptr); } void operator delete(void* ptr, const std::nothrow_t&) throw() { free(ptr); } void operator delete[](void* ptr) throw() { operator delete(ptr); } void operator delete[](void* ptr, const std::nothrow_t&) throw() { operator delete(ptr); }
Exception class for failed memory allocation
class bad_alloc : public exception { public: bad_alloc() throw(); bad_alloc(const bad_alloc&) throw(); bad_alloc& operator=(const bad_alloc&) throw(); virtual ~bad_alloc() throw(); virtual const char* what() const throw(); };
The bad_alloc
class is an exception class that is thrown when the new operator is unable to fulfill a request to allocate memory. As with any of the standard exception classes, what()
returns an implementation-defined character string.
operator new, set_new_handler, exception in <exception>
Type of function that obtains memory
typedef void (*new_handler)();
The new_handler
type is used to declare the se
t
_new_
ha
ndler
function. See set_new_
han
dler
for details.
set_new_handler function
Request null pointer return when out of memory
struct nothrow_t {}; extern const nothrow_t nothrow;
The nothrow
object is used in placement new
expressions to request that the new
operator return a null pointer instead of throwing bad_alloc
if the memory allocation request cannot be fulfilled.
The nothrow_t
type does not do anything; it is used only in overloaded placement new
and delete
operators.
Note that nothrow
is also accepted by an overloaded delete
operator, for symmetry with new
. It has no effect on the delete
operator.
operator delete, operator new
Global delete operator
void operator delete(void* ptr) throw(); void operator delete(void* ptr, const std::nothrow_t&) throw(); void operator delete[](void* ptr) throw(); void operator delete[](void* ptr, const std::nothrow_t&) throw(); void operator delete(void* ptr, void*) throw(); void operator delete[](void* ptr, void*) throw();
The global delete
operator is called from a delete
expression to free memory. The memory, which ptr
points to, must have been returned by a corresponding call to the new
operator or a null pointer. You must not call delete
more than once for the same pointer. If ptr
is null, the delete
operator returns without doing anything.
The first two versions free the memory that ptr
points to, which must have been allocated by calling the plain or nothrow
form of the new
operator. Note that nothrow
has no effect on delete
, which never throws.
The next two versions free memory that was allocated with the array form of new[]
(plain or nothrow
).
The final two versions do nothing. They are called when the corresponding placement new
operator is used.
Unlike other identifiers in the standard library, operator delete
is global, and is not in the std
namespace. Also unlike other functions in the standard library, you can provide your own implementation of operator delete
, which replaces the standard implementation. You cannot replace the last two versions of delete
with your own implementation.
operator delete
Global new operator
void* operator new(std::size_t size) throw(std::bad_alloc); void* operator new(std::size_t size, const std::nothrow_t&) throw(); void* operator new[](std::size_t size) throw(std::bad_alloc); void* operator new[](std::size_t size, const std::nothrow_t&) throw(); void* operator new (std::size_t size, void* ptr) throw(); void* operator new[](std::size_t size, void* ptr) throw();
The global new
operator allocates memory and returns a pointer to the newly allocated memory. The memory must later be released by calling delete
.
The first version of new
allocates at least size
bytes of memory, suitably aligned to store any type, and returns a pointer to the memory. If the request cannot be fulfilled, it throws bad_alloc
.
The second version is like the first, but it returns a null pointer instead of throwing bad_alloc
.
The third version is like the first, but is allocates memory for storing an array of objects. It might allocate more than size
bytes, to permit the library to store additional bookkeeping information. You must call the array form of del
ete
[]
to free this memory.
The fourth version is like the third, but it returns a null pointer instead of throwing bad_
a
lloc
if the memory cannot be allocated.
To allocate memory, the new operators first try to allocate size
bytes, but if they cannot, they call the handler function set by the most recent call to set_new_
h
andler
. Then they try again to allocate size
bytes. This loop repeats until the request is fulfilled or the handler function fails to return.
The final two versions do nothing except return ptr
. These forms permit placement new
expressions to specify a memory location where an object is to be constructed.
Unlike other identifiers in the standard library, operator new
is global, and is not in the std
namespace. Also unlike other functions in the standard library, you can provide your own implementation of operator new
, which replaces the standard implementation.You cannot replace the last two versions of new
with your own implementation.
nothrow object, operator delete, set_new_handler function
Set handler for obtaining memory
new_handler set_new_handler(new_handler new_p) throw();
The set_new_handler
function stores a function pointer for a function that obtains additional memory from the operating system for use by the new operator. When the new
operator is unable to fulfill a request to allocate memory, it calls the handler that was set by the most recent call to set_new_handler
. This handler must do one of the following:
bad_
a
lloc
(or a type that derives from bad_alloc
), orabort()
or exit()
to halt the program.The return value is the pointer to the previous handler, or 0 for the first call to set_new_handler
.
new_handler type