Debian Codegraph @

www/c3ref/mem_methods.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Memory Allocation Routines</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- keywords: sqlite3_mem_methods -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Memory Allocation Routines</h2>
122 </div>
123 <blockquote><pre>
124 typedef struct sqlite3_mem_methods sqlite3_mem_methods;
125 struct sqlite3_mem_methods {
126 void *(*xMalloc)(int); /* Memory allocation function */
127 void (*xFree)(void*); /* Free a prior allocation */
128 void *(*xRealloc)(void*,int); /* Resize an allocation */
129 int (*xSize)(void*); /* Return the size of an allocation */
130 int (*xRoundup)(int); /* Round up request size to allocation size */
131 int (*xInit)(void*); /* Initialize the memory allocator */
132 void (*xShutdown)(void*); /* Deinitialize the memory allocator */
133 void *pAppData; /* Argument to xInit() and xShutdown() */
134 };
135 </pre></blockquote>
136 <p>
137 An instance of this object defines the interface between SQLite
138 and low-level memory allocation routines.</p>
139
140 <p>This object is used in only one place in the SQLite interface.
141 A pointer to an instance of this object is the argument to
142 <a href="../c3ref/config.html">sqlite3_config()</a> when the configuration option is
143 <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>.
144 By creating an instance of this object
145 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>)
146 during configuration, an application can specify an alternative
147 memory allocation subsystem for SQLite to use for all of its
148 dynamic memory needs.</p>
149
150 <p>Note that SQLite comes with several <a href="../malloc.html#altalloc">built-in memory allocators</a>
151 that are perfectly adequate for the overwhelming majority of applications
152 and that this object is only useful to a tiny minority of applications
153 with specialized memory allocation requirements. This object is
154 also used during testing of SQLite in order to specify an alternative
155 memory allocator that simulates memory out-of-memory conditions in
156 order to verify that SQLite recovers gracefully from such
157 conditions.</p>
158
159 <p>The xMalloc, xRealloc, and xFree methods must work like the
160 malloc(), realloc() and free() functions from the standard C library.
161 SQLite guarantees that the second argument to
162 xRealloc is always a value returned by a prior call to xRoundup.</p>
163
164 <p>xSize should return the allocated size of a memory allocation
165 previously obtained from xMalloc or xRealloc. The allocated size
166 is always at least as big as the requested size but may be larger.</p>
167
168 <p>The xRoundup method returns what would be the allocated size of
169 a memory allocation given a particular requested size. Most memory
170 allocators round up memory allocations at least to the next multiple
171 of 8. Some allocators round up to a larger multiple or to a power of 2.
172 Every memory allocation request coming in through <a href="../c3ref/free.html">sqlite3_malloc()</a>
173 or <a href="../c3ref/free.html">sqlite3_realloc()</a> first calls xRoundup. If xRoundup returns 0,
174 that causes the corresponding memory allocation to fail.</p>
175
176 <p>The xInit method initializes the memory allocator. For example,
177 it might allocate any required mutexes or initialize internal data
178 structures. The xShutdown method is invoked (indirectly) by
179 <a href="../c3ref/initialize.html">sqlite3_shutdown()</a> and should deallocate any resources acquired
180 by xInit. The pAppData pointer is used as the only parameter to
181 xInit and xShutdown.</p>
182
183 <p>SQLite holds the <a href="../c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MAIN</a> mutex when it invokes
184 the xInit method, so the xInit method need not be threadsafe. The
185 xShutdown method is only called from <a href="../c3ref/initialize.html">sqlite3_shutdown()</a> so it does
186 not need to be threadsafe either. For all other methods, SQLite
187 holds the <a href="../c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MEM</a> mutex as long as the
188 <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> configuration option is turned on (which
189 it is by default) and so the methods are automatically serialized.
190 However, if <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> is disabled, then the other
191 methods must be threadsafe or else make their own arrangements for
192 serialization.</p>
193
194 <p>SQLite will never invoke xInit() more than once without an intervening
195 call to xShutdown().
196 </p><p>See also lists of
197 <a href="../c3ref/objlist.html">Objects</a>,
198 <a href="../c3ref/constlist.html">Constants</a>, and
199 <a href="../c3ref/funclist.html">Functions</a>.</p>
200