~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>Application Defined Page Cache.</h2><blockquote><pre>typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;

121

struct sqlite3_pcache_methods2 {

122

int iVersion;

123

void *pArg;

124

int (*xInit)(void*);

125

void (*xShutdown)(void*);

126

sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);

127

void (*xCachesize)(sqlite3_pcache*, int nCachesize);

128

int (*xPagecount)(sqlite3_pcache*);

129

sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);

130

void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);

131

void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,

132

unsigned oldKey, unsigned newKey);

133

void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);

134

void (*xDestroy)(sqlite3_pcache*);

135

void (*xShrink)(sqlite3_pcache*);

136

};

137

</pre></blockquote><p>

138

The <a href="../c3ref/config.html">sqlite3_config</a>(<a href="../c3ref/c_config_getmalloc.html#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>, ...) interface can

139

140

instance of the sqlite3_pcache_methods2 structure.

141

In many applications, most of the heap memory allocated by

142

SQLite is used for the page cache.

143

By implementing a

144

custom page cache using this API, an application can better control

145

the amount of memory consumed by SQLite, the way in which

146

that memory is allocated and released, and the policies used to

147

determine exactly which parts of a database file are cached and for

148

how long.</p>

149

150

<p>The alternative page cache mechanism is an

151

extreme measure that is only needed by the most demanding applications.

152

The built-in page cache is recommended for most uses.</p>

153

154

<p>The contents of the sqlite3_pcache_methods2 structure are copied to an

155

internal buffer by SQLite within the call to <a href="../c3ref/config.html">sqlite3_config</a>. Hence

156

the application may discard the parameter after the call to

157

<a href="../c3ref/config.html">sqlite3_config()</a> returns.</p>

158

159

160

161

The xInit() method is called once for each effective

162

call to <a href="../c3ref/initialize.html">sqlite3_initialize()</a>

163

(usually only once during the lifetime of the process). The xInit()

164

method is passed a copy of the sqlite3_pcache_methods2.pArg value.

165

The intent of the xInit() method is to set up global data structures

166

required by the custom page cache implementation.

167

If the xInit() method is NULL, then the

168

built-in default page cache is used instead of the application defined

169

page cache.</p>

170

171

172

173

The xShutdown() method is called by <a href="../c3ref/initialize.html">sqlite3_shutdown()</a>.

174

It can be used to clean up

175

any outstanding resources before process shutdown, if required.

176

The xShutdown() method may be NULL.</p>

177

178

<p>SQLite automatically serializes calls to the xInit method,

179

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. All other methods must be threadsafe

182

in multithreaded applications.</p>

183

184

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

185

call to xShutdown().</p>

186

187

188

189

SQLite invokes the xCreate() method to construct a new cache instance.

190

SQLite will typically create one cache instance for each open database file,

191

though this is not guaranteed. The

192

first parameter, szPage, is the size in bytes of the pages that must

193

be allocated by the cache. szPage will always a power of two. The

194

second parameter szExtra is a number of bytes of extra storage

195

associated with each page cache entry. The szExtra parameter will

196

a number less than 250. SQLite will use the

197

extra szExtra bytes on each page to store metadata about the underlying

198

database page on disk. The value passed into szExtra depends

199

on the SQLite version, the target platform, and how SQLite was compiled.

200

The third argument to xCreate(), bPurgeable, is true if the cache being

201

created will be used to cache database pages of a file stored on disk, or

202

false if it is used for an in-memory database. The cache implementation

203

does not have to do anything special based with the value of bPurgeable;

204

it is purely advisory. On a cache where bPurgeable is false, SQLite will

205

never invoke xUnpin() except to deliberately delete a page.

206

In other words, calls to xUnpin() on a cache with bPurgeable set to

207

false will always have the "discard" flag set to true.

208

Hence, a cache created with bPurgeable false will

209

never contain any unpinned pages.</p>

210

211

212

213

The xCachesize() method may be called at any time by SQLite to set the

214

suggested maximum cache-size (number of pages stored by) the cache

215

instance passed as the first argument. This is the value configured using

216

the SQLite "<a href="../pragma.html#pragma_cache_size">PRAGMA cache_size</a>" command. As with the bPurgeable

217

parameter, the implementation is not required to do anything with this

218

value; it is advisory only.</p>

219

220

221

222

The xPagecount() method must return the number of pages currently

223

stored in the cache, both pinned and unpinned.</p>

224

225

226

227

The xFetch() method locates a page in the cache and returns a pointer to

228

an sqlite3_pcache_page object associated with that page, or a NULL pointer.

229

The pBuf element of the returned sqlite3_pcache_page object will be a

230

pointer to a buffer of szPage bytes used to store the content of a

231

single database page. The pExtra element of sqlite3_pcache_page will be

232

a pointer to the szExtra bytes of extra storage that SQLite has requested

233

for each entry in the page cache.</p>

234

235

<p>The page to be fetched is determined by the key. The minimum key value

236

is 1. After it has been retrieved using xFetch, the page is considered

237

to be "pinned".</p>

238

239

<p>If the requested page is already in the page cache, then the page cache

240

implementation must return a pointer to the page buffer with its content

241

intact. If the requested page is not already in the cache, then the

242

cache implementation should use the value of the createFlag

243

parameter to help it determined what action to take:</p>

244

245

246

<tr><th> createFlag <th> Behaviour when page is not already in cache

247

<tr><td> 0 <td> Do not allocate a new page. Return NULL.

248

<tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.

249

Otherwise return NULL.

250

<tr><td> 2 <td> Make every effort to allocate a new page. Only return

251

NULL if allocating a new page is effectively impossible.

252

</table></p>

253

254

<p>SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite

255

will only use a createFlag of 2 after a prior call with a createFlag of 1

256

failed. In between the to xFetch() calls, SQLite may

257

attempt to unpin one or more cache pages by spilling the content of

258

pinned pages to disk and synching the operating system disk cache.</p>

259

260

261

262

xUnpin() is called by SQLite with a pointer to a currently pinned page

263

as its second argument. If the third parameter, discard, is non-zero,

264

then the page must be evicted from the cache.

265

If the discard parameter is

266

zero, then the page may be discarded or retained at the discretion of

267

page cache implementation. The page cache implementation

268

may choose to evict unpinned pages at any time.</p>

269

270

<p>The cache must not perform any reference counting. A single

271

call to xUnpin() unpins the page regardless of the number of prior calls

272

to xFetch().</p>

273

274

275

276

The xRekey() method is used to change the key value associated with the

277

page passed as the second argument. If the cache

278

previously contains an entry associated with newKey, it must be

279

discarded. Any prior cache entry associated with newKey is guaranteed not

280

to be pinned.</p>

281

282

<p>When SQLite calls the xTruncate() method, the cache must discard all

283

existing cache entries with page numbers (keys) greater than or equal

284

to the value of the iLimit parameter passed to xTruncate(). If any

285

of these pages are pinned, they are implicitly unpinned, meaning that

286

they can be safely discarded.</p>

287

288

289

290

The xDestroy() method is used to delete a cache allocated by xCreate().

291

All resources associated with the specified cache should be freed. After

292

calling the xDestroy() method, SQLite considers the <a href="../c3ref/pcache.html">sqlite3_pcache*</a>

293

handle invalid, and will not use it with any other sqlite3_pcache_methods2

294

functions.</p>

295

296

297

298

SQLite invokes the xShrink() method when it wants the page cache to

299

free up as much of heap memory as possible. The page cache implementation

300

is not obligated to free any memory, but well-behaved implementations should

301

do their best.

302

</p><p>See also lists of

303

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

304

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

305

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