~ubuntu-branches/ubuntu/wily/sqlite3/wily

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...">

112

113

</form>

114

</div>

115

</table>

116

</div></div></div></div>

117

</td></tr></table>

118

119

120

<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;

121

struct sqlite3_mem_methods {

122

void *(*xMalloc)(int); /* Memory allocation function */

123

void (*xFree)(void*); /* Free a prior allocation */

124

void *(*xRealloc)(void*,int); /* Resize an allocation */

125

int (*xSize)(void*); /* Return the size of an allocation */

126

int (*xRoundup)(int); /* Round up request size to allocation size */

127

int (*xInit)(void*); /* Initialize the memory allocator */

128

void (*xShutdown)(void*); /* Deinitialize the memory allocator */

129

void *pAppData; /* Argument to xInit() and xShutdown() */

130

};

131

</pre></blockquote><p>

132

An instance of this object defines the interface between SQLite

133

and low-level memory allocation routines.</p>

134

135

<p>This object is used in only one place in the SQLite interface.

136

A pointer to an instance of this object is the argument to

137

<a href="../c3ref/config.html">sqlite3_config()</a> when the configuration option is

138

<a href="../c3ref/c_config_getmalloc.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a> or <a href="../c3ref/c_config_getmalloc.html#sqliteconfiggetmalloc">SQLITE_CONFIG_GETMALLOC</a>.

139

By creating an instance of this object

140

and passing it to <a href="../c3ref/config.html">sqlite3_config</a>(<a href="../c3ref/c_config_getmalloc.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>)

141

during configuration, an application can specify an alternative

142

memory allocation subsystem for SQLite to use for all of its

143

dynamic memory needs.</p>

144

145

<p>Note that SQLite comes with several <a href="../malloc.html#altalloc">built-in memory allocators</a>

146

that are perfectly adequate for the overwhelming majority of applications

147

and that this object is only useful to a tiny minority of applications

148

with specialized memory allocation requirements. This object is

149

also used during testing of SQLite in order to specify an alternative

150

memory allocator that simulates memory out-of-memory conditions in

151

order to verify that SQLite recovers gracefully from such

152

conditions.</p>

153

154

<p>The xMalloc, xRealloc, and xFree methods must work like the

155

malloc(), realloc() and free() functions from the standard C library.

156

SQLite guarantees that the second argument to

157

xRealloc is always a value returned by a prior call to xRoundup.</p>

158

159

<p>xSize should return the allocated size of a memory allocation

160

previously obtained from xMalloc or xRealloc. The allocated size

161

is always at least as big as the requested size but may be larger.</p>

162

163

<p>The xRoundup method returns what would be the allocated size of

164

a memory allocation given a particular requested size. Most memory

165

allocators round up memory allocations at least to the next multiple

166

of 8. Some allocators round up to a larger multiple or to a power of 2.

167

Every memory allocation request coming in through <a href="../c3ref/free.html">sqlite3_malloc()</a>

168

or <a href="../c3ref/free.html">sqlite3_realloc()</a> first calls xRoundup. If xRoundup returns 0,

169

that causes the corresponding memory allocation to fail.</p>

170

171

<p>The xInit method initializes the memory allocator. (For example,

172

it might allocate any require mutexes or initialize internal data

173

structures. The xShutdown method is invoked (indirectly) by

174

<a href="../c3ref/initialize.html">sqlite3_shutdown()</a> and should deallocate any resources acquired

175

by xInit. The pAppData pointer is used as the only parameter to

176

xInit and xShutdown.</p>

177

178

<p>SQLite holds the <a href="../c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MASTER</a> mutex when it invokes

179

the xInit method, so the xInit method need not be threadsafe. The

180

xShutdown method is only called from <a href="../c3ref/initialize.html">sqlite3_shutdown()</a> so it does

181

not need to be threadsafe either. For all other methods, SQLite

182

holds the <a href="../c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MEM</a> mutex as long as the

183

<a href="../c3ref/c_config_getmalloc.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> configuration option is turned on (which

184

it is by default) and so the methods are automatically serialized.

185

However, if <a href="../c3ref/c_config_getmalloc.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> is disabled, then the other

186

methods must be threadsafe or else make their own arrangements for

187

serialization.</p>

188

189

<p>SQLite will never invoke xInit() more than once without an intervening

190

call to xShutdown().

191

</p><p>See also lists of

192

<a href="objlist.html">Objects</a>,

193

<a href="constlist.html">Constants</a>, and

194

<a href="funclist.html">Functions</a>.</p>