<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Dynamic Memory</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="support.html" title="Chapter 4. Support" /><link rel="prev" href="support.html" title="Chapter 4. Support" /><link rel="next" href="termination.html" title="Termination" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Dynamic Memory</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="support.html">Prev</a> </td><th width="60%" align="center">Chapter 4.
Support
</th><td width="20%" align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.support.memory"></a>Dynamic Memory</h2></div></div></div><p>
In C++98 there are six flavors each of <code class="function">operator new</code>
and <code class="function">operator delete</code>, so make certain that you're
using the right ones.
Here are quickie descriptions of <code class="function">operator new</code>:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="code">void* operator new(std::size_t);</code></span></dt><dd>
Single object form.
Throws <code class="classname">std::bad_alloc</code> on error.
This is what most people are used to using.
</dd><dt><span class="term"><code class="code">void* operator new(std::size_t, std::nothrow_t) noexcept;</code></span></dt><dd>
Single object <span class="quote">“<span class="quote">nothrow</span>”</span> form.
Calls <code class="code">operator new(std::size_t)</code> but if that throws,
returns a null pointer instead.
</dd><dt><span class="term"><code class="code">void* operator new[](std::size_t);</code></span></dt><dd>
Array <code class="function">new</code>.
Calls <code class="code">operator new(std::size_t)</code> and so
throws <code class="classname">std::bad_alloc</code> on error.
</dd><dt><span class="term"><code class="code">void* operator new[](std::size_t, std::nothrow_t) noexcept;</code></span></dt><dd>
Array <span class="quote">“<span class="quote">nothrow</span>”</span><code class="function">new</code>.
Calls <code class="code">operator new[](std::size_t)</code> but if that throws,
returns a null pointer instead.
</dd><dt><span class="term"><code class="code">void* operator new(std::size_t, void*) noexcept;</code></span></dt><dd>
Non-allocating, <span class="quote">“<span class="quote">placement</span>”</span> single-object <code class="function">new</code>,
which does nothing except return its argument.
This function cannot be replaced.
</dd><dt><span class="term"><code class="code">void* operator new[](std::size_t, void*) noexcept;</code></span></dt><dd>
Non-allocating, <span class="quote">“<span class="quote">placement</span>”</span> array <code class="function">new</code>,
which also does nothing except return its argument.
This function cannot be replaced.
</dd></dl></div><p>
They are distinguished by the arguments that you pass to them, like
any other overloaded function. The six flavors of
<code class="function">operator delete</code>
are distinguished the same way, but none of them are allowed to throw
an exception under any circumstances anyhow. (The overloads match up
with the ones above, for completeness' sake.)
</p><p>
The C++ 2014 revision of the standard added two additional overloads of
<code class="function">operator delete</code> for <span class="quote">“<span class="quote">sized deallocation</span>”</span>,
allowing the compiler to provide the size of the storage being freed.
</p><p>
The C++ 2017 standard added even more overloads of both
<code class="function">operator new</code> and <code class="function">operator delete</code>
for allocating and deallocating storage for overaligned types.
These overloads correspond to each of the allocating forms of
<code class="function">operator new</code> and <code class="function">operator delete</code>
but with an additional parameter of type <span class="type">std::align_val_t</span>.
These new overloads are not interchangeable with the versions without
an aligment parameter, so if memory was allocated by an overload of
<code class="function">operator new</code> taking an alignment parameter,
then it must be decallocated by the corresponding overload of
<code class="function">operator delete</code> that takes an alignment parameter.
</p><p>
Apart from the non-allocating forms, the default versions of the array
and nothrow <code class="function">operator new</code> functions will all result
in a call to either <code class="function">operator new(std::size_t)</code> or
<code class="function">operator new(std::size_t, std::align_val_t)</code>,
and similarly the default versions of the array and nothrow
<code class="function">operator delete</code> functions will result in a call to
either <code class="function">operator delete(void*)</code> or
<code class="function">operator delete(void*, std::align_val_t)</code>
(or the sized versions of those).
</p><p>
Apart from the non-allocating forms, any of these functions can be
replaced by defining a function with the same signature in your program.
Replacement versions must preserve certain guarantees, such as memory
obtained from a nothrow <code class="function">operator new</code> being free-able
by the normal (non-nothrow) <code class="function">operator delete</code>,
and the sized and unsized forms of <code class="function">operator delete</code>
being interchangeable (because it's unspecified whether
the compiler calls the sized delete instead of the normal one).
The simplest way to meet the guarantees is to only replace the ordinary
<code class="function">operator new(size_t)</code> and
<code class="function">operator delete(void*)</code> and
<code class="function">operator delete(void*, std::size_t)</code>
functions, and the replaced versions will be used by all of
<code class="function">operator new(size_t, nothrow_t)</code>,
<code class="function">operator new[](size_t)</code> and
<code class="function">operator new[](size_t, nothrow_t)</code>
and the corresponding <code class="function">operator delete</code> functions.
To support types with extended alignment you may also need to replace
<code class="function">operator new(size_t, align_val_t)</code> and
<code class="function">operator delete(void*, align_val_t)</code>
<code class="function">operator delete(void*, size_t, align_val_t)</code>
(which will then be used by the nothrow and array forms for
extended alignments).
If you do need to replace other forms (e.g. to define the nothrow
<code class="function">operator new</code> to allocate memory directly, so it
works with exceptions disabled) then make sure the memory it allocates
can still be freed by the non-nothrow forms of
<code class="function">operator delete</code>.
</p><p>
If the default versions of <code class="function">operator new(std::size_t)</code>
and <code class="function">operator new(size_t, std::align_val_t)</code>
can't allocate the memory requested, they usually throw an exception
object of type <code class="classname">std::bad_alloc</code> (or some class
derived from that). However, the program can influence that behavior
by registering a <span class="quote">“<span class="quote">new-handler</span>”</span>, because what
<code class="function">operator new</code> actually does is something like:
</p><pre class="programlisting">
while (true)
{
if (void* p = /* try to allocate memory */)
return p;
else if (std::new_handler h = std::get_new_handler ())
h ();
else
throw bad_alloc{};
}
</pre><p>
This means you can influence what happens on allocation failure by
writing your own new-handler and then registering it with
<code class="function">std::set_new_handler</code>:
</p><pre class="programlisting">
typedef void (*PFV)();
static char* safety;
static PFV old_handler;
void my_new_handler ()
{
delete[] safety;
safety = nullptr;
popup_window ("Dude, you are running low on heap memory. You"
" should, like, close some windows, or something."
" The next time you run out, we're gonna burn!");
set_new_handler (old_handler);
return;
}
int main ()
{
safety = new char[500000];
old_handler = set_new_handler (&my_new_handler);
...
}
</pre><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="std.support.memory.notes"></a>Additional Notes</h3></div></div></div><p>
Remember that it is perfectly okay to <code class="function">delete</code> a
null pointer! Nothing happens, by definition. That is not the
same thing as deleting a pointer twice.
</p><p>
<code class="classname">std::bad_alloc</code> is derived from the base
<code class="classname">std::exception</code> class,
see <a class="xref" href="diagnostics.html#std.diagnostics.exceptions" title="Exceptions">Exceptions</a>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="support.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4.
Support
</td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Termination</td></tr></table></div></body></html>