1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!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.�� 3 Support 4 5</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> 6 In C++98 there are six flavors each of <code class="function">operator new</code> 7 and <code class="function">operator delete</code>, so make certain that you're 8 using the right ones. 9 Here are quickie descriptions of <code class="function">operator new</code>: 10 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="code">void* operator new(std::size_t);</code></span></dt><dd> 11 Single object form. 12 Throws <code class="classname">std::bad_alloc</code> on error. 13 This is what most people are used to using. 14 </dd><dt><span class="term"><code class="code">void* operator new(std::size_t, std::nothrow_t) noexcept;</code></span></dt><dd> 15 Single object <span class="quote">���<span class="quote">nothrow</span>���</span> form. 16 Calls <code class="code">operator new(std::size_t)</code> but if that throws, 17 returns a null pointer instead. 18 </dd><dt><span class="term"><code class="code">void* operator new[](std::size_t);</code></span></dt><dd> 19 Array <code class="function">new</code>. 20 Calls <code class="code">operator new(std::size_t)</code> and so 21 throws <code class="classname">std::bad_alloc</code> on error. 22 </dd><dt><span class="term"><code class="code">void* operator new[](std::size_t, std::nothrow_t) noexcept;</code></span></dt><dd> 23 Array <span class="quote">���<span class="quote">nothrow</span>���</span><code class="function">new</code>. 24 Calls <code class="code">operator new[](std::size_t)</code> but if that throws, 25 returns a null pointer instead. 26 </dd><dt><span class="term"><code class="code">void* operator new(std::size_t, void*) noexcept;</code></span></dt><dd> 27 Non-allocating, <span class="quote">���<span class="quote">placement</span>���</span> single-object <code class="function">new</code>, 28 which does nothing except return its argument. 29 This function cannot be replaced. 30 </dd><dt><span class="term"><code class="code">void* operator new[](std::size_t, void*) noexcept;</code></span></dt><dd> 31 Non-allocating, <span class="quote">���<span class="quote">placement</span>���</span> array <code class="function">new</code>, 32 which also does nothing except return its argument. 33 This function cannot be replaced. 34 </dd></dl></div><p> 35 They are distinguished by the arguments that you pass to them, like 36 any other overloaded function. The six flavors of 37 <code class="function">operator delete</code> 38 are distinguished the same way, but none of them are allowed to throw 39 an exception under any circumstances anyhow. (The overloads match up 40 with the ones above, for completeness' sake.) 41 </p><p> 42 The C++ 2014 revision of the standard added two additional overloads of 43 <code class="function">operator delete</code> for <span class="quote">���<span class="quote">sized deallocation</span>���</span>, 44 allowing the compiler to provide the size of the storage being freed. 45 </p><p> 46 The C++ 2017 standard added even more overloads of both 47 <code class="function">operator new</code> and <code class="function">operator delete</code> 48 for allocating and deallocating storage for overaligned types. 49 These overloads correspond to each of the allocating forms of 50 <code class="function">operator new</code> and <code class="function">operator delete</code> 51 but with an additional parameter of type <span class="type">std::align_val_t</span>. 52 These new overloads are not interchangeable with the versions without 53 an aligment parameter, so if memory was allocated by an overload of 54 <code class="function">operator new</code> taking an alignment parameter, 55 then it must be decallocated by the corresponding overload of 56 <code class="function">operator delete</code> that takes an alignment parameter. 57 </p><p> 58 Apart from the non-allocating forms, the default versions of the array 59 and nothrow <code class="function">operator new</code> functions will all result 60 in a call to either <code class="function">operator new(std::size_t)</code> or 61 <code class="function">operator new(std::size_t, std::align_val_t)</code>, 62 and similarly the default versions of the array and nothrow 63 <code class="function">operator delete</code> functions will result in a call to 64 either <code class="function">operator delete(void*)</code> or 65 <code class="function">operator delete(void*, std::align_val_t)</code> 66 (or the sized versions of those). 67 </p><p> 68 Apart from the non-allocating forms, any of these functions can be 69 replaced by defining a function with the same signature in your program. 70 Replacement versions must preserve certain guarantees, such as memory 71 obtained from a nothrow <code class="function">operator new</code> being free-able 72 by the normal (non-nothrow) <code class="function">operator delete</code>, 73 and the sized and unsized forms of <code class="function">operator delete</code> 74 being interchangeable (because it's unspecified whether 75 the compiler calls the sized delete instead of the normal one). 76 The simplest way to meet the guarantees is to only replace the ordinary 77 <code class="function">operator new(size_t)</code> and 78 <code class="function">operator delete(void*)</code> and 79 <code class="function">operator delete(void*, std::size_t)</code> 80 functions, and the replaced versions will be used by all of 81 <code class="function">operator new(size_t, nothrow_t)</code>, 82 <code class="function">operator new[](size_t)</code> and 83 <code class="function">operator new[](size_t, nothrow_t)</code> 84 and the corresponding <code class="function">operator delete</code> functions. 85 To support types with extended alignment you may also need to replace 86 <code class="function">operator new(size_t, align_val_t)</code> and 87 <code class="function">operator delete(void*, align_val_t)</code> 88 <code class="function">operator delete(void*, size_t, align_val_t)</code> 89 (which will then be used by the nothrow and array forms for 90 extended alignments). 91 If you do need to replace other forms (e.g. to define the nothrow 92 <code class="function">operator new</code> to allocate memory directly, so it 93 works with exceptions disabled) then make sure the memory it allocates 94 can still be freed by the non-nothrow forms of 95 <code class="function">operator delete</code>. 96 </p><p> 97 If the default versions of <code class="function">operator new(std::size_t)</code> 98 and <code class="function">operator new(size_t, std::align_val_t)</code> 99 can't allocate the memory requested, they usually throw an exception 100 object of type <code class="classname">std::bad_alloc</code> (or some class 101 derived from that). However, the program can influence that behavior 102 by registering a <span class="quote">���<span class="quote">new-handler</span>���</span>, because what 103 <code class="function">operator new</code> actually does is something like: 104 </p><pre class="programlisting"> 105 while (true) 106 { 107 if (void* p = /* try to allocate memory */) 108 return p; 109 else if (std::new_handler h = std::get_new_handler ()) 110 h (); 111 else 112 throw bad_alloc{}; 113 } 114 </pre><p> 115 This means you can influence what happens on allocation failure by 116 writing your own new-handler and then registering it with 117 <code class="function">std::set_new_handler</code>: 118 </p><pre class="programlisting"> 119 typedef void (*PFV)(); 120 121 static char* safety; 122 static PFV old_handler; 123 124 void my_new_handler () 125 { 126 delete[] safety; 127 safety = nullptr; 128 popup_window ("Dude, you are running low on heap memory. You" 129 " should, like, close some windows, or something." 130 " The next time you run out, we're gonna burn!"); 131 set_new_handler (old_handler); 132 return; 133 } 134 135 int main () 136 { 137 safety = new char[500000]; 138 old_handler = set_new_handler (&my_new_handler); 139 ... 140 } 141 </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> 142 Remember that it is perfectly okay to <code class="function">delete</code> a 143 null pointer! Nothing happens, by definition. That is not the 144 same thing as deleting a pointer twice. 145 </p><p> 146 <code class="classname">std::bad_alloc</code> is derived from the base 147 <code class="classname">std::exception</code> class, 148 see <a class="xref" href="diagnostics.html#std.diagnostics.exceptions" title="Exceptions">Exceptions</a>. 149 </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.�� 150 Support 151 152��</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>