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"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Dbstl memory management</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="stl.html" title="Chapter��7.��Standard Template Library API" /> 11 <link rel="prev" href="stl_efficienct_use.html" title="Using dbstl efficiently" /> 12 <link rel="next" href="stl_misc.html" title="Dbstl miscellaneous notes" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Dbstl memory management</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="stl_efficienct_use.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��7.��Standard Template Library API</th> 23 <td width="20%" align="right">��<a accesskey="n" href="stl_misc.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="stl_memory_mgmt"></a>Dbstl memory management</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="stl_memory_mgmt.html#id1602244">Freeing memory</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="stl_memory_mgmt.html#id1602395">Type specific notes</a> 46 </span> 47 </dt> 48 </dl> 49 </div> 50 <div class="sect2" lang="en" xml:lang="en"> 51 <div class="titlepage"> 52 <div> 53 <div> 54 <h3 class="title"><a id="id1602244"></a>Freeing memory</h3> 55 </div> 56 </div> 57 </div> 58 <p> 59 When using dbstl, make sure memory allocated in the heap is 60 released after use. The rules for this are: 61 </p> 62 <div class="itemizedlist"> 63 <ul type="disc"> 64 <li> 65 <p> 66 dbstl will free/delete any memory allocated by dbstl itself. 67 </p> 68 </li> 69 <li> 70 <p> 71 You are responsible for freeing/deleting any memory allocated by your code outside of dbstl. 72 </p> 73 </li> 74 </ul> 75 </div> 76 </div> 77 <div class="sect2" lang="en" xml:lang="en"> 78 <div class="titlepage"> 79 <div> 80 <div> 81 <h3 class="title"><a id="id1602395"></a>Type specific notes</h3> 82 </div> 83 </div> 84 </div> 85 <div class="sect3" lang="en" xml:lang="en"> 86 <div class="titlepage"> 87 <div> 88 <div> 89 <h4 class="title"><a id="id1602915"></a>DbEnv/Db</h4> 90 </div> 91 </div> 92 </div> 93 <p> 94 When you open a <code class="classname">DbEnv</code> or <code class="classname">Db</code> object using 95 <code class="methodname">dbstl::open_env()</code> or <code class="methodname">dbstl::open_db()</code>, you 96 do not need to delete that object. However, if you new'd that object and then opened it 97 without using the <code class="methodname">dbstl::open_env()</code> or 98 <code class="methodname">dbstl::open_db()</code> methods, you are responsible for deleting the 99 object. 100 </p> 101 <p> 102 Note that you must <code class="literal">new</code> the <code class="classname">Db</code> or 103 <code class="classname">DbEnv</code> object, which allocates it on the heap. You can not allocate it 104 on the stack. If you do, the order of destruction is uncontrollable, which makes dbstl 105 unable to work properly. 106 </p> 107 <p> 108 You can call <code class="function">dbstl_exit()</code> before the process exits, to release any 109 memory allocated by dbstl that has to live during the entire process lifetime. Releasing the 110 memory explicitly will not make much difference, because the process is about to exit and so 111 all memory allocated on the heap is going to be returned to the operating system anyway. The 112 only real difference is that your memory leak checker will not report false memory leaks. 113 </p> 114 <p> 115 <code class="function">dbstl_exit()</code> releases any memory allocated by dbstl on the heap. It 116 also performs other required shutdown operations, such as closing any databases and 117 environments registered to dbstl and shared across the process. 118 </p> 119 <p> 120 If you are calling the <code class="function">dbstl_exit()</code> function, and your 121 <code class="classname">DbEnv</code> or <code class="classname">Db</code> objects are new'd by your code, 122 the <code class="function">dbstl_exit()</code> function should be called before deleting the 123 <code class="classname">DbEnv</code> or <code class="classname">Db</code> objects, because they need to be 124 closed before being deleted. Alternatively, you can call the 125 <code class="methodname">dbstl::close_env()</code> or <code class="methodname">dbstl::close_db()</code> 126 functions before deleting the <code class="classname">DbEnv</code> or <code class="classname">Db</code> 127 objects in order to explicitly close the databases or environments. If you do this, 128 can then delete these objects, and then call <code class="function">dbstl_exit()</code>. 129 </p> 130 </div> 131 <div class="sect3" lang="en" xml:lang="en"> 132 <div class="titlepage"> 133 <div> 134 <div> 135 <h4 class="title"><a id="id1602901"></a>DbstlDbt</h4> 136 </div> 137 </div> 138 </div> 139 <p> 140 Only when you are storing raw bytes (such as a bitmap) do you have to 141 store and retrieve data by using the <code class="classname">DbstlDbt</code> helper class. Although you 142 also can do so simply by using the Berkeley DB <code class="classname">Dbt</code> class, the 143 <code class="classname">DbstlDbt</code> class offers more convenient memory management behavior. 144 </p> 145 <p> 146 When you are storing <code class="classname">DbstlDbt</code> objects (such as 147 <code class="classname">db_vector<DbstlDbt></code>), you <span class="emphasis"><em>must</em></span> allocate 148 heap memory explicitly using the <code class="function">malloc()</code> function for the 149 <code class="classname">DbstlDbt</code> object to reference, but you do not need to free the memory 150 ��� it is automatically freed by the <code class="classname">DbstlDbt</code> object that owns it 151 by calling the standard C library <code class="function">free()</code> function. 152 </p> 153 <p> 154 However, because dbstl supports storing any type of object or primitive data, it is rare 155 that you would have to store data using <code class="classname">DbstlDbt</code> objects while using 156 dbstl. Examples of storing <code class="classname">DbstlDbt</code> objects can be found in the 157 <code class="methodname">TestAssoc::test_arbitrary_object_storage()</code> and 158 <code class="methodname">TestAssoc::test_char_star_string_storage()</code> functions, which are 159 available in the dbstl test suite. 160 </p> 161 </div> 162 </div> 163 </div> 164 <div class="navfooter"> 165 <hr /> 166 <table width="100%" summary="Navigation footer"> 167 <tr> 168 <td width="40%" align="left"><a accesskey="p" href="stl_efficienct_use.html">Prev</a>��</td> 169 <td width="20%" align="center"> 170 <a accesskey="u" href="stl.html">Up</a> 171 </td> 172 <td width="40%" align="right">��<a accesskey="n" href="stl_misc.html">Next</a></td> 173 </tr> 174 <tr> 175 <td width="40%" align="left" valign="top">Using dbstl efficiently��</td> 176 <td width="20%" align="center"> 177 <a accesskey="h" href="index.html">Home</a> 178 </td> 179 <td width="40%" align="right" valign="top">��Dbstl miscellaneous notes</td> 180 </tr> 181 </table> 182 </div> 183 </body> 184</html> 185