Placement syntax

The placement overloads of operator new and operator delete that employ an additional void * parameter are used for default placement, also known as pointer placement. Their definitions by the Standard C++ library, which it is not permitted for a C++ program to replace or override, are:[7][8][9]

void* operator new(std::size_t, void* p) throw() { return p; }
void* operator new[](std::size_t, void* p) throw() { return p; }
void operator delete(void*, void*) throw() { }
void operator delete[](void*, void*) throw() { }

There are various uses for default placement.

Bjarne Stroustrup originally observed, in his book The Design and Evolution of C++, that pointer placement new is necessary for hardware that expects a certain object at a specific hardware address. It is also required for the construction of objects that need to reside in a certain memory area, such as an area that is shared between several processors of a multiprocessor computer.[10]

Other uses, however, include calling a constructor directly, something which the C++ language does not otherwise permit.[3]

The C++ language does allow a program to call a destructor directly, and, since it is not possible to destroy the object using a delete expression, that is how one destroys an object that was constructed via a pointer placement new expression. For example:[11][12]

p->~T();

Placement new is used when you do not want operator new to allocate memory (you have pre-allocated it and you want to place the object there), but you do want the object to be constructed. Examples of typical situations where this may be required are:

• You want to create objects in memory shared between two different processes.
• You want objects to be created in non-pageable memory.
• You want to separate memory allocation from construction e.g. in implementing a std::vector<> (see std::vector<>::reserve).

The basic problem is that the constructor is a peculiar function; when it starts off, there is no object, only raw memory. And by the time it finishes, you have a fully initialized object. Therefore, i) The constructor cannot be called on an object ii) However, it needs to access (and initialize) non-static members. This makes calling the constructor directly an error. The solution is the placement form of operator new.

This operator is implemented as:

    void* operator new(std::size_t count, void* here) { return here; }
    void* operator new[](std::size_t count, void* here) { return here; }

Normally, the (non-placement) new functions throw an exception, of type std::bad_alloc, if they encounter an error, such as exhaustion of all available memory. This was not how the functions were defined by Stroustrup's Annotated C++ Reference Manual, but was a change made by the standardization committee when the C++ language was standardized. The original behaviour of the functions, which was to return a NULL pointer when an error occurred, is accessible via placement syntax.[3][4][6]

Programmers who wish to do this in their programs must include the Standard C++ library header <new> in the source code. This header declares the global std::nothrow object, which is of type std::nothrow_t (also declared in the header), which is used to call the overloaded new functions that are declared as taking const std::nothrow_t & as their second parameter. For example:[9]

#include <new>

struct T {};

int main() {
    // Call the function operator new(std::size_t, const std::nothrow_t &) and (if successful) construct the object.
    T* p = new (std::nothrow) T;
    if (p) {
        // The storage has been allocated and the constructor called.
        delete p;
    } else
        ; // An error has occurred.  No storage has been allocated and no object constructed.
    return 0;
}

Placement syntax is also employed for custom allocators. This does not use any of the allocator and deallocator functions from the Standard C++ library header <new>, but requires that programmers write their own allocation and deallocation functions, overloaded for user-defined types. For example, one could define a memory management class as follows:[7][8]

#include <cstdlib>
class A {
public:
    void* allocate(std::size_t);
    void deallocate(void*);
};

And define custom placement allocation and deallocation functions as follows:[7][8]

void* operator new(std::size_t size, A& arena) {
    return arena.allocate(size);
}

void operator delete(void* p, A& arena) {
    arena.deallocate(p);
}

The program would employ the placement syntax to allocate objects using different instances of the A class as follows:[7][8]

A first_arena, second_arena;
T* p1 = new(first_arena) T;
T* p2 = new(second_arena) T;

Destroying an object whose storage is allocated in such a fashion requires some care. Because there is no placement delete expression, one cannot use it to invoke the custom deallocator. One must either write a destruction function that invokes the custom deallocator, or call the placement delete function directly, as a function call.[11][7][8]

The former would resemble:[8]

void destroy(T* p, A& arena) {
    p->~T();  // First invoke the destructor explicitly.
    arena.deallocate(p);  // Then call the deallocator function directly.
}

which would be invoked from a program as:

A arena;
T* p = new(arena) T;
/* ... */
destroy(p, arena);

The latter would involve simply writing the destructor invocation and delete function call into the program:[7][13]

A arena;
T* p = new(arena) T;
/* ... */
p->~T();  // First invoke the destructor explicitly.
operator delete(p, arena);  // Then call the deallocator function indirectly via operator delete(void*, A &).

A common error is to attempt to use a delete expression to delete the object. This results in the wrong operator delete function being called. Dewhurst recommends two strategies for avoiding this error. The first is to ensure that any custom allocators rely upon the Standard C++ library's global, non-placement, operator new, and are thus nothing more than simple wrappers around the C++ library's memory management. The second is to create new and delete functions for individual classes, and customize memory management via class function members rather than by using the placement syntax.[13]

Placement new can also be used as a simple debugging tool, to enable programs to print the filename and line number of the source code where a memory allocation has failed. This does not require the inclusion of the Standard C++ library header <new>, but does require the inclusion of a header that declares four placement functions and a macro replacement for the new keyword that is used in new expressions. For example, such a header would contain:[9][14]

#if defined(DEBUG_NEW)
void* operator new(std::size_t size, const char* file, int line);
void* operator new[](std::size_t size, const char* file, int line);
void operator delete(void* p, const char* file, int line);
void operator delete[](void* p, const char* file, int line);
#define New new(__FILE__, __LINE__)
#else
#define New new
#endif

This would be employed in a program as follows:[9][14]

T* p = New T;

The custom-written placement new functions would then handle using the supplied file and line number information in the event of an exception. For example:[9][14]

#include <new>
#include <cstdlib>

class NewError {
public:
    NewError(const char* file, int line) { /* ... */ }
    /* ... */
} ;

void *
operator new(std::size_t size, const char* file, int line)
{
    if (void* p = ::operator new(size, std::nothrow))
        return p;
    throw NewError(file, line);
}