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