-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
-C Remove\san\sunreachable\sbranch\sfrom\swhere.c\sin\sorder\sto\srestore\s100%\nbranch\stest\scoverage.\s\sAdd\sassert()\sand\stestcase()\smacros\sto\sverify\nthat\sthe\sbranch\sis\sunreachable.
-D 2009-08-25T16:28:14
+C Updates\sto\sthe\spluggable\spage\scache\sdocumentation.
+D 2009-08-26T00:26:52
F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0
F Makefile.in 73ddeec9dd10b85876c5c2ce1fdce627e1dcc7f8
F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
F src/rowset.c c64dafba1f9fd876836c8db8682966b9d197eb1f
F src/select.c 67b0778c9585905c8aa75aaa469e76ef3c1d315a
F src/shell.c db2643650b9268df89a4bedca3f1c6d9e786f1bb
-F src/sqlite.h.in fdd4e3109e21431797a22e3696d082c271a454fc
+F src/sqlite.h.in 9d03ceaad971882482c158c0e3d39d361c2c18a1
F src/sqlite3ext.h 1db7d63ab5de4b3e6b83dd03d1a4e64fef6d2a17
F src/sqliteInt.h 20ab1da1a9a652ea673e5bc586382143914381c0
F src/sqliteLimit.h ffe93f5a0c4e7bd13e70cd7bf84cfb5c3465f45d
F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
F tool/vdbe-compress.tcl 672f81d693a03f80f5ae60bfefacd8a349e76746
-P 3fb3686a4502140720dc3710a28a4f4128ab6554
-R dc2ce485398987f32fbd08b4b9b6e9a2
+P 58db7e7166ccefef77b237b77e17f47d31ff41e0
+R 9f12b5b75ef341ad213d2e64e3b8bf27
U drh
-Z 0483859ddb44e8db8724d5ac5d7b3598
+Z 1d42b9a29de3d8a356c2ced8b35a64c1
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
-iD8DBQFKlBEhoxKgR168RlERAoNOAJwMp0k4JWVXC1dwpKqMRdWTaxDFOgCfQdCh
-DU43moi3lq58zHhTjn6ZCMk=
-=MsO6
+iD8DBQFKlIFPoxKgR168RlERAk9bAJ0VKEBOAKWI3SN/4tpXs8KZIAdMzACgir+A
+32mtwR9OZj3gr61fgTQ88fE=
+=+tcK
-----END PGP SIGNATURE-----
/*
** CAPI3REF: Application Defined Page Cache.
+** KEYWORDS: {page cache}
** EXPERIMENTAL
**
** The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
** from, or ready to be written to, the database file. By implementing a
** custom page cache using this API, an application can control more
** precisely the amount of memory consumed by SQLite, the way in which
-** said memory is allocated and released, and the policies used to
+** that memory is allocated and released, and the policies used to
** determine exactly which parts of a database file are cached and for
** how long.
**
-** The contents of the structure are copied to an internal buffer by SQLite
-** within the call to [sqlite3_config].
+** The contents of the sqlite3_pcache_methods structure are copied to an
+** internal buffer by SQLite within the call to [sqlite3_config]. Hence
+** the application may discard the parameter after the call to
+** [sqlite3_config()] returns.
**
** The xInit() method is called once for each call to [sqlite3_initialize()]
** (usually only once during the lifetime of the process). It is passed
** SQLite will never invoke xInit() more than once without an intervening
** call to xShutdown().
**
-** The xCreate() method is used to construct a new cache instance. The
+** The xCreate() method is used to construct a new cache instance. SQLite
+** will typically create one cache instance for each open database file,
+** though this is not guaranteed. The
** first parameter, szPage, is the size in bytes of the pages that must
-** be allocated by the cache. szPage will not be a power of two. The
-** second argument, bPurgeable, is true if the cache being created will
-** be used to cache database pages read from a file stored on disk, or
+** be allocated by the cache. szPage will not be a power of two. szPage
+** will the page size of the database file that is to be cached plus an
+** increment (here called "R") of about 100 or 200. SQLite will use the
+** extra R bytes on each page to store metadata about the underlying
+** database page on disk. The value of R depends
+** on the SQLite version, the target platform, and how SQLite was compiled.
+** R is constant for a particular build of SQLite. The second argument to
+** xCreate(), bPurgeable, is true if the cache being created will
+** be used to cache database pages of a file stored on disk, or
** false if it is used for an in-memory database. The cache implementation
-** does not have to do anything special based on the value of bPurgeable,
-** it is purely advisory.
+** does not have to do anything special based with the value of bPurgeable;
+** it is purely advisory. On a cache where bPurgeable is false, SQLite will
+** never invoke xUnpin() except to deliberately delete a page.
+** In other words, a cache created with bPurgeable set to false will
+** never contain any unpinned pages.
**
** The xCachesize() method may be called at any time by SQLite to set the
** suggested maximum cache-size (number of pages stored by) the cache
** instance passed as the first argument. This is the value configured using
** the SQLite "[PRAGMA cache_size]" command. As with the bPurgeable parameter,
-** the implementation is not required to do anything special with this
-** value, it is advisory only.
+** the implementation is not required to do anything with this
+** value; it is advisory only.
**
** The xPagecount() method should return the number of pages currently
-** stored in the cache supplied as an argument.
+** stored in the cache.
**
** The xFetch() method is used to fetch a page and return a pointer to it.
** A 'page', in this context, is a buffer of szPage bytes aligned at an
** 8-byte boundary. The page to be fetched is determined by the key. The
** mimimum key value is 1. After it has been retrieved using xFetch, the page
-** is considered to be pinned.
+** is considered to be "pinned".
**
-** If the requested page is already in the page cache, then a pointer to
-** the cached buffer should be returned with its contents intact. If the
-** page is not already in the cache, then the expected behaviour of the
-** cache is determined by the value of the createFlag parameter passed
-** to xFetch, according to the following table:
+** If the requested page is already in the page cache, then the page cache
+** implementation must return a pointer to the page buffer with its content
+** intact. If the requested page is not already in the cache, then the
+** behavior of the cache implementation is determined by the value of the
+** createFlag parameter passed to xFetch, according to the following table:
**
** <table border=1 width=85% align=center>
-** <tr><th>createFlag<th>Expected Behaviour
-** <tr><td>0<td>NULL should be returned. No new cache entry is created.
-** <tr><td>1<td>If createFlag is set to 1, this indicates that
-** SQLite is holding pinned pages that can be unpinned
-** by writing their contents to the database file (a
-** relatively expensive operation). In this situation the
-** cache implementation has two choices: it can return NULL,
-** in which case SQLite will attempt to unpin one or more
-** pages before re-requesting the same page, or it can
-** allocate a new page and return a pointer to it. If a new
-** page is allocated, then the first sizeof(void*) bytes of
-** it (at least) must be zeroed before it is returned.
-** <tr><td>2<td>If createFlag is set to 2, then SQLite is not holding any
-** pinned pages associated with the specific cache passed
-** as the first argument to xFetch() that can be unpinned. The
-** cache implementation should attempt to allocate a new
-** cache entry and return a pointer to it. Again, the first
-** sizeof(void*) bytes of the page should be zeroed before
-** it is returned. If the xFetch() method returns NULL when
-** createFlag==2, SQLite assumes that a memory allocation
-** failed and returns SQLITE_NOMEM to the user.
+** <tr><th> createFlag <th> Behaviour when page is not already in cache
+** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
+** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
+** Otherwise return NULL.
+** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
+** NULL if allocating a new page is effectively impossible.
** </table>
**
+** SQLite will normally invoke xFetch() with a createFlag of 0 or 1. If
+** a call to xFetch() with createFlag==1 returns NULL, then SQLite will
+** attempt to unpin one or more cache pages by spilling the content of
+** pinned pages to disk and synching the operating system disk cache. After
+** attempting to unpin pages, the xFetch() method will be invoked again with
+** a createFlag of 2.
+**
** xUnpin() is called by SQLite with a pointer to a currently pinned page
** as its second argument. If the third parameter, discard, is non-zero,
** then the page should be evicted from the cache. In this case SQLite
** assumes that the next time the page is retrieved from the cache using
** the xFetch() method, it will be zeroed. If the discard parameter is
** zero, then the page is considered to be unpinned. The cache implementation
-** may choose to reclaim (free or recycle) unpinned pages at any time.
-** SQLite assumes that next time the page is retrieved from the cache
-** it will either be zeroed, or contain the same data that it did when it
-** was unpinned.
+** may choose to evict unpinned pages at any time.
**
** The cache is not required to perform any reference counting. A single
** call to xUnpin() unpins the page regardless of the number of prior calls
projects / thirdparty / sqlite.git / commitdiff
