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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Memory Allocation Routines</title>
<style type="text/css">
body {
margin: auto;
font-family: Verdana, sans-serif;
padding: 8px 1%;
}
a { color: #044a64 }
a:visited { color: #734559 }
.logo { position:absolute; margin:3px; }
.tagline {
float:right;
text-align:right;
font-style:italic;
width:300px;
margin:12px;
margin-top:58px;
}
.menubar {
clear: both;
border-radius: 8px;
background: #044a64;
padding: 0px;
margin: 0px;
cell-spacing: 0px;
}
.toolbar {
text-align: center;
line-height: 1.6em;
margin: 0;
padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }
.content { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }
/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a { color: darkblue ; text-decoration: none }
.fancy .todo { color: #AA3333 ; font-style : italic }
.fancy .todo:before { content: 'TODO:' }
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */
</style>
</head>
<body>
<div><!-- container div to satisfy validator -->
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
<table width=100% class="menubar"><tr>
<td width=100%>
<div class="toolbar">
<a href="../about.html">About</a>
<a href="../sitemap.html">Sitemap</a>
<a href="../docs.html">Documentation</a>
<a href="../download.html">Download</a>
<a href="../copyright.html">License</a>
<a href="../news.html">News</a>
<a href="../support.html">Support</a>
</div>
<script>
gMsg = "Search SQLite Docs..."
function entersearch() {
var q = document.getElementById("q");
if( q.value == gMsg ) { q.value = "" }
q.style.color = "black"
q.style.fontStyle = "normal"
}
function leavesearch() {
var q = document.getElementById("q");
if( q.value == "" ) {
q.value = gMsg
q.style.color = "#044a64"
q.style.fontStyle = "italic"
}
}
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
</script>
<td>
<div style="padding:0 1em 0px 0;white-space:nowrap">
<form name=f method="GET" action="http://www.sqlite.org/search">
<input id=q name=q type=text
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
</form>
</div>
</table>
<div class=startsearch></div>
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Memory Allocation Routines</h2><blockquote><pre>typedef struct sqlite3_mem_methods sqlite3_mem_methods;
struct sqlite3_mem_methods {
void *(*xMalloc)(int); /* Memory allocation function */
void (*xFree)(void*); /* Free a prior allocation */
void *(*xRealloc)(void*,int); /* Resize an allocation */
int (*xSize)(void*); /* Return the size of an allocation */
int (*xRoundup)(int); /* Round up request size to allocation size */
int (*xInit)(void*); /* Initialize the memory allocator */
void (*xShutdown)(void*); /* Deinitialize the memory allocator */
void *pAppData; /* Argument to xInit() and xShutdown() */
};
</pre></blockquote><p>
An instance of this object defines the interface between SQLite
and low-level memory allocation routines.</p>
<p>This object is used in only one place in the SQLite interface.
A pointer to an instance of this object is the argument to
<a href="../c3ref/config.html">sqlite3_config()</a> when the configuration option is
<a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a> or <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfiggetmalloc">SQLITE_CONFIG_GETMALLOC</a>.
By creating an instance of this object
and passing it to <a href="../c3ref/config.html">sqlite3_config</a>(<a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>)
during configuration, an application can specify an alternative
memory allocation subsystem for SQLite to use for all of its
dynamic memory needs.</p>
<p>Note that SQLite comes with several <a href="../malloc.html#altalloc">built-in memory allocators</a>
that are perfectly adequate for the overwhelming majority of applications
and that this object is only useful to a tiny minority of applications
with specialized memory allocation requirements. This object is
also used during testing of SQLite in order to specify an alternative
memory allocator that simulates memory out-of-memory conditions in
order to verify that SQLite recovers gracefully from such
conditions.</p>
<p>The xMalloc, xRealloc, and xFree methods must work like the
malloc(), realloc() and free() functions from the standard C library.
SQLite guarantees that the second argument to
xRealloc is always a value returned by a prior call to xRoundup.</p>
<p>xSize should return the allocated size of a memory allocation
previously obtained from xMalloc or xRealloc. The allocated size
is always at least as big as the requested size but may be larger.</p>
<p>The xRoundup method returns what would be the allocated size of
a memory allocation given a particular requested size. Most memory
allocators round up memory allocations at least to the next multiple
of 8. Some allocators round up to a larger multiple or to a power of 2.
Every memory allocation request coming in through <a href="../c3ref/free.html">sqlite3_malloc()</a>
or <a href="../c3ref/free.html">sqlite3_realloc()</a> first calls xRoundup. If xRoundup returns 0,
that causes the corresponding memory allocation to fail.</p>
<p>The xInit method initializes the memory allocator. For example,
it might allocate any require mutexes or initialize internal data
structures. The xShutdown method is invoked (indirectly) by
<a href="../c3ref/initialize.html">sqlite3_shutdown()</a> and should deallocate any resources acquired
by xInit. The pAppData pointer is used as the only parameter to
xInit and xShutdown.</p>
<p>SQLite holds the <a href="../c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MASTER</a> mutex when it invokes
the xInit method, so the xInit method need not be threadsafe. The
xShutdown method is only called from <a href="../c3ref/initialize.html">sqlite3_shutdown()</a> so it does
not need to be threadsafe either. For all other methods, SQLite
holds the <a href="../c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MEM</a> mutex as long as the
<a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> configuration option is turned on (which
it is by default) and so the methods are automatically serialized.
However, if <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> is disabled, then the other
methods must be threadsafe or else make their own arrangements for
serialization.</p>
<p>SQLite will never invoke xInit() more than once without an intervening
call to xShutdown().
</p><p>See also lists of
<a href="objlist.html">Objects</a>,
<a href="constlist.html">Constants</a>, and
<a href="funclist.html">Functions</a>.</p>
|
