Draft 2002-08-12

<new>

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);
}

bad_alloc class

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.

See Also

operator new, set_new_handler, exception in <exception>

new_handler type

Type of function that obtains memory

typedef void (*new_handler)();

The new_handler type is used to declare the set_new_handler function. See set_new_handler for details.

See Also

set_new_handler function

nothrow object

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.

See Also

operator delete, operator new

operator delete

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.

See Also

operator delete

operator new

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 delete[] to free this memory.

The fourth version is like the third, but it returns a null pointer instead of throwing bad_alloc 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_handler. 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.

See Also

nothrow object, operator delete, set_new_handler function

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:

The return value is the pointer to the previous handler, or 0 for the first call to set_new_handler.

See Also

new_handler type