operator new, operator new[]

From cppreference.com
< cpp‎ | memory‎ | new
 
C++
 
Utilities library
Type support (basic types, RTTI, type traits)
Dynamic memory management
Error handling
Program utilities
Variadic functions
Date and time
Function objects
(C++11)
(C++11)
Relational operators
Optional and any
(C++17)
(C++17)
Pairs and tuples
(C++11)
(C++17)
(C++11)
(C++11)
(C++14)
Swap, forward and move
(C++14)
(C++11)
(C++11)
(C++11)
Type operations
(C++11)
(C++17)
 
Dynamic memory management
 
Low level memory management
Functions
operator newoperator new[]
(C++11)
Classes
(C++11)
Types
Objects
 
Defined in header <new>
replaceable allocation functions
void* operator new  ( std::size_t count );
 (1)
void* operator new[]( std::size_t count );
 (2)
void* operator new  ( std::size_t count, const std::nothrow_t& tag);
 (3)
void* operator new[]( std::size_t count, const std::nothrow_t& tag);
 (4)
placement allocation functions
void* operator new  ( std::size_t count, void* ptr );
 (5)
void* operator new[]( std::size_t count, void* ptr );
 (6)
void* operator new  ( std::size_t count, user-defined-args... );
 (7)
void* operator new[]( std::size_t count, user-defined-args... );
 (8)
class-specific allocation functions
void* T::operator new  ( std::size_t count );
 (9)
void* T::operator new[]( std::size_t count );
 (10)
void* T::operator new  ( std::size_t count, user-defined-args... );
 (11)
void* T::operator new[]( std::size_t count, user-defined-args... );
 (12)

Allocates requested number of bytes. These allocation functions are called by new-expressions to allocate memory in which new object would then be initialized. They may also be called using regular function call syntax.

1) Called by non-array new-expressions to allocate storage required for a single object. The standard library implementation allocates count bytes from free store. In case of failure, the standard library implementation calls the function pointer returned by std::get_new_handler and repeats allocation attempts until new handler does not return or becomes a null pointer, at which time it throws std::bad_alloc. This function is required to return a pointer suitably aligned to hold an object of any fundamental alignment.
2) Called by the array form of new[]-expressions to allocate all storage required for an array (including possible new-expression overhead). The standard library implementation calls version (1)
3) Called by the non-throwing non-array new-expressions . The standard library implementation calls the version (1) and returns a null pointer on failure instead of propagating the exception.
4) Called by the non-throwing array form of new[]-expressions. The standard library implementation calls the version (2) and returns a null pointer on failure instead of propagating the exception.
5) Called by the standard single-object placement new expression. The standard library implementation performs no action and returns ptr unmodified.
6) Called by the standard array form placement new expression. The standard library implementation performs no action and returns ptr unmodified.
7) If defined, called by the custom single-object placement new expression with the matching signature. If a class-specific version (11) is defined, it is called in preference to (7). If neither (7) nor (11) is provided by the user, the placement new expression is ill-formed.
8) If defined, called by the custom array form placement new expression with the matching signature. If a class-specific version (12) is defined, it is called in preference to (8). If neither (8) nor (12) is provided by the user, the placement new expression is ill-formed.
9) If defined, called by the usual single-object new-expressions if allocating an object of type T.
10) If defined, called by the usual array new[]-expressions if allocating an array of objects of type T.
11) If defined, called by the custom single-object placement new expression with the matching signature if allocating an object of type T.
12) If defined, called by the custom array form of placement new[] expression with the matching signature if allocating an array of objects of type T.

Contents

[edit] Parameters

count - number of bytes to allocate
ptr - pointer to a memory area to initialize the object at
tag - disambiguation tag used to select non-throwing overloads

[edit] Return value

non-null pointer to suitably aligned memory of size at least size

[edit] Exceptions

1-2,9-10) throws std::bad_alloc or another exception derived from std::bad_alloc (since C++11) on failure to allocate memory
3-6)
(none) (until C++11)
noexcept specification:  
noexcept
  
 (since C++11)

[edit] Global replacements

The versions (1-4) are implicitly declared in each translation unit even if the <new> header is not included. These functions are replaceable: a user-provided non-member function with the same signature defined anywhere in the program, in any source file, replaces the implicit version. Its declaration does not need to be visible.

The behavior is undefined if more than one replacement is provided in the program for any of the four implicit allocation function, or if a replacement is defined with the inline specifier. The program is ill-formed if a replacement is defined in namespace other than global namespace, or if it is defined as a static non-member function at global scope.

The single-object version (1) is directly called by the standard library implementations of all other versions (2-4), so replacing that one function is sufficient to handle all allocations. (since C++11)
Run this code
#include <cstdio>
#include <cstdlib>
// replacement of a minimal set of functions:
void* operator new(std::size_t sz) {
    std::printf("global op new called, size = %zu\n",sz);
    return std::malloc(sz);
}
void operator delete(void* ptr) noexcept
{
    std::puts("global op delete called");
    std::free(ptr);
}
int main() {
     int* p1 = new int;
     delete p1;
 
     int* p2 = new int[10]; // guaranteed to call the replacement in C++11
     delete[] p2;
}

Possible output: 

global op new called, size = 4
global op delete called
global op new called, size = 40
global op delete called

Overloads of operator new and operator new[] with additional user-defined parameters ("placement forms", version 7-8) may be declared at global scope as usual, and are called by the matching placement forms of new-expressions.

The standard library placement forms of operator new (5-6) cannot be replaced and can only be customized if the placement new-expression did not use the ::new syntax, by providing a class-specific placement new (11-12) with matching signature: void* T::operator new(size_t, void*) or void* T::operator new[](size_t, void*).

The placement form void* operator new(size_t, size_t) is not allowed because the matching signature of the deallocation function, void operator delete(void*, size_t), is a usual (not placement) deallocation function.

(since C++14)

[edit] Class-specific overloads

Both single-object and array allocation functions may be defined as public static member functions of a class (versions 9-10). If defined, these allocation functions are called by new-expressions to allocate memory for single objects and arrays of this class, unless the new expression used the form ::new which bypasses class-scope lookup. The keyword static is optional for these functions: whether used or not, the allocation function is a static member function.

The new expression looks for appropriate allocation function's name firstly in the class scope, and after that in the global scope. Note, that as per name lookup rules, any allocation functions declared in class scope hides all global allocation functions for the new-expressions that attempt to allocate objects of this class.

Run this code
#include <iostream>
// class-specific allocation functions
struct X {
    static void* operator new(std::size_t sz)
    {
        std::cout << "custom new for size " << sz << '\n';
        return ::operator new(sz);
    }
    static void* operator new[](std::size_t sz)
    {
        std::cout << "custom new for size " << sz << '\n';
        return ::operator new(sz);
    }
};
int main() {
     X* p1 = new X;
     delete p1;
     X* p2 = new X[10];
     delete[] p2;
}

Possible output: 

custom new for size 1
custom new for size 10

Overloads of operator new and operator new[] with additional user-defined parameters ("placement forms", versions 11 and 12) may also be defined as class members. When the placement new expression with the matching signature looks for the corresponding allocation function to call, it begins at class scope before examining the global scope, and if the class-specific placement new is provided, it is called.

Run this code
#include <stdexcept>
#include <iostream>
struct X {
    X() { throw std::runtime_error(""); }
    // custom placement new
    static void* operator new(std::size_t sz, bool b) {
        std::cout << "custom placement new called, b = " << b << '\n';
        return ::operator new(sz);
    }
    // custom placement delete
    static void operator delete(void* ptr, bool b)
    {
        std::cout << "custom placement delete called, b = " << b << '\n';
        ::operator delete(ptr);
    }
};
int main() {
   try {
     X* p1 = new (true) X;
   } catch(const std::exception&) { }
}

Output: 

custom placement new called, b = 1
custom placement delete called, b = 1

If class-level operator new is a template function, it must have the return type of void*, the first argument size_t, and it must have two or more parameters. In other words, only placement forms can be templates.

[edit] Notes

Even though placement new (overloads 5 and 6) cannot be replaced, a function with the same signature may be defined at class scope as described above. In addition, global overloads that look like placement new but take a non-void pointer type as the second argument are allowed, so the code that wants to ensure that the true placement new is called (e.g. std::allocator::construct), must use ::new and also cast the pointer to void*.

[edit] Example

Custom placement forms of operator new can be used for any purpose, for example, to fill the allocated array

Run this code
#include <iostream>
#include <algorithm>
 
void* operator new[](std::size_t sz, char c)
{
    void* p = operator new[](sz);
    std::fill_n(reinterpret_cast<char*>(p), sz, c);
    return p;
}
 
int main()
{
    char* p = new('*') char[6];
    p[5] = '\0';
    std::cout << p << '\n';
    delete[] p;
}

Output: 

*****

[edit] See also

deallocation functions
(function)
(C++11)
 obtains the current new handler
(function)
registers a new handler
(function)
obtains uninitialized storage
(function)
allocates memory
(function)

[edit] References

  • C++11 standard (ISO/IEC 14882:2011):
  • 18.6 Dynamic memory management [support.dynamic]
Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/memory/new/operator_new&oldid=77392"