Content deleted Content added
Cybercobra (talk | contribs) m layout; Disambiguated: pointer (computing) → pointer (computer programming) (2) |
add std:: prefix to size_t and nothrow_t |
||
Line 3:
The "placement" versions of the <code>[[new (C++)|new]]</code> and <code>[[delete (C++)|delete]]</code> operators and functions are known as placement <code>new</code> and placement <code>delete</code>.<ref name=McCluskey2000 /> A <code>new</code> ''expression'', placement or otherwise, calls a <code>new</code> ''function'', also known as an allocator function, whose name is <code>operator new</code>. Similarly, a <code>delete</code> ''expression'' calls a <code>delete</code> ''function'', also known as a deallocator function, whose name is <code>operator delete</code>.<ref name=Lischner2003 /><ref name=Lippman1997 />
Any <code>new</code> expression that uses the placement syntax is a placement <code>new</code> expression, and any <code>operator new</code> or <code>operator delete</code> function that takes more than the mandatory first parameter (<source lang="cpp" enclose=none>std::size_t</source> and <source lang="cpp" enclose=none>void *</source>, respectively) is a placement new or placement delete function.<ref name=Meyers1998 />
== History ==
Line 20:
The placement new functions are overloads of the non-placement new functions. The declaration of the non-placement new functions, for non-array and array <code>new</code> expressions respectively, are:<ref name=Vermeir2001 /><ref name=Stroustrup1997b />
:<source lang="cpp" enclose=div>
void * operator new (std::size_t) throw(std::bad_alloc);
void * operator new[] (std::size_t) throw(std::bad_alloc);
</source>
The Standard C++ library provides two placement overloads each for these functions. Their declarations are:<ref name=Vermeir2001 /><ref name=Stroustrup1997b />
:<source lang="cpp" enclose=div>
void * operator new (std::size_t, const std::nothrow_t &) throw();
void * operator new (std::size_t, void *) throw();
void * operator new[] (std::size_t, const std::nothrow_t &) throw();
void * operator new[] (std::size_t, void *) throw();
</source>
In all of the overloads, the first parameter to the <code>operator new</code> function is of type <source lang="cpp" enclose=none>std::size_t</source>, which when the function is called will be passed as an argument the amount of memory, in bytes, to allocate. All of the functions must return type <source lang="cpp" enclose=none>void *</source>, which is a [[pointer (computer programming)|pointer]] to the storage that the function allocates.<ref name=Lischner2003 />
There are also placement delete functions. They are overloaded versions of the non-placement delete functions. The non-placement delete functions are declared as:<ref name=Vermeir2001 /><ref name=Stroustrup1997b />
Line 58:
The placement overloads of <code>operator new</code> and <code>operator delete</code> that employ an additional <source lang="cpp" enclose=none>void *</source> 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:<ref name=Vermeir2001 /><ref name=Stroustrup1997b /><ref name=Anderson1998a />
:<source lang="cpp" enclose=div>
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() { }
Line 80:
Normally, the (non-placement) new functions throw an exception, of type <code>std::bad_alloc</code>, 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 <source lang="cpp" enclose=none>NULL</source> pointer when an error occurred, is accessible via placement syntax.<ref name=Lippman1997 /><ref name=Meyers1998 /><ref name=Loudon2003 />
Programmers who wish to do this in their programs must include the Standard C++ library header <code><new></code> in the source code. This header declares the global <code>std::nothrow</code> object, which is of type <code>std::nothrow_t</code> (also declared in the header), which is used to call the overloaded new functions that are declared as taking <source lang="cpp" enclose=none>const std::nothrow_t &</source> as their second parameter. For example:<ref name=Anderson1998a />
:<source lang="cpp" enclose=div>
#include <new>
Line 88:
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) {
Line 105:
class A {
public:
void * allocate ( std::size_t ) ;
void deallocate ( void * ) ;
} ;
Line 113:
:<source lang="cpp" enclose=div>
void *
operator new (std::size_t size, A & arena)
{
return arena.allocate(size) ;
Line 165:
:<source lang="cpp" enclose=div>
#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);
Line 192:
void *
operator new (std::size_t size, const char* file, int line)
{
if (void * p = ::operator new (size, std::nothrow))
Line 217:
} ;
void * operator new ( std::size_t, const A & ) ;
void operator delete ( void *, const A & ) ;
| |||