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
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="../sqlite.css" rel="stylesheet">
<title>Memory Allocation Routines</title>
<!-- path=../ -->
</head>
<body>
<div class=nosearch>
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="../index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='../about.html'>About</a>
<li class='desktoponly'><a href="../docs.html">Documentation</a>
<li class='desktoponly'><a href="../download.html">Download</a>
<li class='wideonly'><a href='../copyright.html'>License</a>
<li class='desktoponly'><a href="../support.html">Support</a>
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='../about.html'>About</a>
<li><a href='../docs.html'>Documentation</a>
<li><a href='../download.html'>Download</a>
<li><a href='../support.html'>Support</a>
<li><a href='../prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="../search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
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;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<!-- keywords: sqlite3_mem_methods -->
<div class=nosearch>
<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
<h2>Memory Allocation Routines</h2>
</div>
<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 required 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_MAIN</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="../c3ref/objlist.html">Objects</a>,
<a href="../c3ref/constlist.html">Constants</a>, and
<a href="../c3ref/funclist.html">Functions</a>.</p>
|
