The Placement New Operator

I’d like to shed a little bit of light on a dusty corner of the C++ language: there’s more than one “new” operator! Well, since you’ve likely encountered the vector new (new[]) operator, I should say there’s more than two “new” operators! I want to cover the concept of a “placement new” operator.

In C++, you cannot call a constructor directly. There’s no way for you to say: someTest->Test(). This makes sense; how would you get an instance of someTest without having called one of it constructors first? But this leaves an interesting problem for the programmer — what do you do when you want to take care of the allocation side of things yourself, but want the compiler to still call your constructor?

There’s the “shotgun” approach where you simply define an operator new function at the global scope. Now every time new is called, your operator new function is fired and you’ve got control over the allocation. But what do you do when you only want the special behavior for some particular class or classes? Then you can do the “rifle” approach where you define an operator new function within the classes you wish to control allocation of. In this way, your new allocator will be called when an instance of your special class is required, but the default new allocator will be called every other time. But this still leaves another case unhandled: what if you want to use the special allocator sometimes, but not other times? That’s where the placement new operator comes in — you can overload this operator, and then the choice goes to the developer as to whether they want to use the special allocator or not when creating the class instance.

Why would you ever want to do this?

Before I answer that question, I want to go into what the placement new operator looks like, how it’s typically used, and what problems can crop up from it.

Creating the placement new operator function is quite similar to creating a regular new operator function.

// Regular operator new
void *operator new( std::size_t size );

// "Placement" operator new
void *operator new( std::size_t size, <your parameters here> );

You have complete control over what parameters show up after the size parameter, and what parameters you pick depend entirely on what you want to use the function for. The C++ language specification defines two different placement new operators (well, technically there are four, since two are scalar and two are vector):

// Section 18.6.1.1 Clause 5
void* operator new(std::size_t size, const std::nothrow_t&) throw();
// Section 18.6.1.3 Clause 1
void* operator new (std::size_t size, void* ptr) throw();

The first form is a way for you to call new without having it throw an exception if problems occur during allocation. The second form is a way for you to call new and say “do not allocate memory, just use this memory I’ve already provided for you.” The way you use these at a call site is:

SomeClass *sc = new (std::nothrow) SomeClass( 1, 2, 3 );

void *memory = ::malloc( sizeof( SomeClass ) );
SomeClass *sc2 = new (memory) SomeClass( 1, 2, 3 );

Just like there is a placement new operator, there is a placement delete operator. It looks sensibly similar to a regular delete:

// Regular operator delete
void operator delete( void *memory );
// "Placement" operator delete
void operator delete( void *memory, <your parameters here>);

However, the placement delete operator is a bit of an oddity — the only time placement delete will be called is if the initializer or constructor called during a placement new throws an exception. This is required because otherwise there’s potential for a memory leak to happen. However, once the object is fully constructed, the placement delete operator will never be called for that instance!

This brings up an interesting question — from our example code above, how do we destroy the SomeClass object for sc2? Normally, we’d say “call delete on it”, except what would that do? It would fire the destructor method, which is good. But then it would call a deallocation function (operator delete), which can’t possibly know how to free the memory we used in the placement new. The answer is: you explicitly call the destructor yourself!

sc2->~SomeClass();
// Presumably the memory for sc2 will be freed or reclaimed some time later

So what about the sc object? Do we have to call the destructor explicitly there too? The answer to that lies in the C++ specification, Section 18.6.1.1 Clauses 7 and 8. You can imagine the std::nothrow_t version of new to be implemented like this:

void *operator new( std::size_t size, std::nothrow_t ) throw() {
	try {
		return ::operator new( size );
	} catch (std::bad_alloc) {
		return nullptr;
	}
}

Because the non-throwing version of operator new simply calls through to the regular version of new, it is safe to use delete to destroy classes created in this fashion. This brings up a very key distinction that may be easy to miss: there’s nothing magical about the placement versions of operator new, they simply change the way you need to think about allocation and deallocation. That is all these operators are designed to do — so if your class’ placement new function allocates memory, you can define an operator delete method on that class to handle deallocation as well. Just remember that you still need to have the placement delete in case construction fails!

Here’s a contrived example (of something you should never, ever do, I might add!) that allows us to allocate more space than the class requires so that we can “lump together” the class and some of its contained data. Please note that I don’t condone using this for production use (I’ve not exactly thought this code all the way through).

#include <new>
#include <stdio.h>

class Test {
private:
	char *mData;
	size_t mDataLength;

	// Disallow use of the default new operator!
	static void *operator new( std::size_t ) = delete;

public:
	Test( const char *data, size_t dataLength ) : mData( nullptr ), mDataLength( dataLength ) {
		// We have a special allocator so we can keep our data close.  The mData pointer
		// should point to a space directly after the end of our this pointer.  We can
		// then move the passed data into that memory.
		//
		// NOTE: this is scary.  Don't do this in production code.
		mData = (char *)(((unsigned char *)this) + sizeof( Test ));
		::memcpy( mData, data, dataLength );
	}

	~Test() {
		// Note: we don't have to free the mData pointer because it's taken care of for
		// us by our custom allocation functions.
	}

	const char *GetData() const { return mData; }

	static void *operator new( std::size_t size, unsigned short extra ) {
		return ::operator new( size + extra );
	}

	static void operator delete( void *memory, unsigned short extra ) {
		operator delete( memory );
	}

	static void operator delete( void *memory ) {
		::operator delete( memory );
	}
};

int main( void )
{
	const char *kStr = "This is my crazy string";
	unsigned short len = static_cast< unsigned short >( ::strlen( kStr ) + 1 );	// Allocate an extra byte for the null terminator
	
	Test *t = new (len) Test( kStr, len );
	::printf( "Test lives at 0x%p\nIts data lives at 0x%p and is %s", t, t->GetData(), t->GetData() );
	delete t;

	return 0;
}

If you run this example code, you’ll notice that the data pointer truly does follow after the class pointer, and the data is valid. The way it works is by calling the placement new operator that is defined within the Test class, which calls through to the global operator new function. It simply is increasing the size of the requested memory allocation to account for our extra data. In the constructor, we skip to the end of our class’s space in memory and copy in our string data directly following the class. We can write our constructor like that safely because we know we have removed the ability to call the non-placement new! (Note, if your compiler does not support deleted methods, you can simply remove the “= delete” and not define the method body.) When the user has finished with their class instance, they call our operator delete method, which calls through to the global operator delete to perform the destruction.

There are a few interesting details here though. First, since we know the constructor does not throw any exceptions, why do we define a placement delete? The specification does not make any demands that a matching placement deallocation function be present, however it is still good form. Whenever you have a custom allocator, making a custom deallocator to match it is just good coding practice. Some compilers even enforce this, such as VC++ (at least, as of Visual Studio 2010 this is true). The second question which comes up is, why do we define a class-level operator delete that simply calls through to the global one? Again, it seems that some compilers simply require this (likely due to it being good practice). However, according to Section 12.5 Clause 4, if the class-level operator delete is not found, it should search the class hierarchy and end with the globally defined operator delete. Yet in VC++ (2010), the compiler claims the delete operator cannot be reached without defining it on the class. The last interesting detail is in the signature of the placement new and placement delete functions themselves: why use unsigned short?

At first, I would have used std::size_t, because that is the result of strlen, and is the most appropriate type to use. However, it would cause a problem with the placement delete function, because operator delete actually has two standard forms:

void operator delete( void *memory );
void operator delete( void *memory, std::size_t size );

Either one of those is considered to be a “usual” deallocation function, according to Section 3.7.4.2 Clause 2. So this creates for ambiguity with the placement version of operator delete — is it acting as a placement version, or acting as a usual deletion? This exact scenario is called out in Section 5.3.4 Clause 20, and if we were to do it, the program would be ill-formed. However, VC++ does allow you to do this, and will give you proper behavior.

Earlier, I asked you why you would ever want to use the placement new operator. There are three answers to that question:

• Non-throwing versions of new
• Discriminated unions
• Arenas or Zones

We’ve already discussed the non-throwing version of new, but let’s talk a bit about discrimated unions and arenas.

Let’s say we have the following union declaration:

union {
	int i;
	float f;
	std::string s;
} u;

Since we cannot call constructors directly, the only way to properly initialize the string member of that union is by using the placement new operator. The union has already allocated the space for the class, and so we can simply use that with the default placement new. When we are done, we don’t need to free any memory (the union owns that), but we do need to call the string’s destructor. So our usage would look like this:

union u myUnion;
new (&myUnion.s) string( "My string value ");
// Do something with myUnion.s
myUnion.s.~String();

Effectively, this is the only way to call non-trivial constructors and destructors with discriminated unions.

Arenas are the last interesting reason why you might want to use placement operators. Let’s say that you have an application which communicates via shared memory. You can use a placement new operator to pick whether a class is allocated into the shared memory region, or the private memory region of the application. These memory regions are generally called “arenas” or “zones.” As a programmer, you can create custom allocator classes which allow you to allocate into different arenas, and the caller can determine whether they wish to use placement syntax to use one arena over another.

The placement new operator is not something you are likely to run across frequently (except for, possibly, the std::nothrow_t version). However, it’s one of those areas of C++ that is helpful to know exists. It’s not a general purpose tool within the language, but when you need the level of control it provides, it can be invaluable.