From: drh Date: Wed, 26 Aug 2009 00:26:51 +0000 (+0000) Subject: Updates to the pluggable page cache documentation. X-Git-Tag: fts3-refactor~222 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=67fba2805541f205749b2bc76cc1e1eba57254d2;p=thirdparty%2Fsqlite.git Updates to the pluggable page cache documentation. FossilOrigin-Name: 3085ad7612e2c50a2d7906e82b2d057954d9c3f9 --- diff --git a/manifest b/manifest index 3e3dffe860..498c08a08f 100644 --- a/manifest +++ b/manifest @@ -1,8 +1,8 @@ -----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 @@ -163,7 +163,7 @@ F src/resolve.c 4a61d03e49b15440878096e6030863fc628828f0 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 @@ -750,14 +750,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff 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----- diff --git a/manifest.uuid b/manifest.uuid index eb5fda7b49..fea0005d9e 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -58db7e7166ccefef77b237b77e17f47d31ff41e0 \ No newline at end of file +3085ad7612e2c50a2d7906e82b2d057954d9c3f9 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index addb893a23..eabed6e710 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -5251,6 +5251,7 @@ typedef struct sqlite3_pcache sqlite3_pcache; /* ** CAPI3REF: Application Defined Page Cache. +** KEYWORDS: {page cache} ** EXPERIMENTAL ** ** The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can @@ -5260,12 +5261,14 @@ typedef struct sqlite3_pcache sqlite3_pcache; ** 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 @@ -5286,71 +5289,71 @@ typedef struct sqlite3_pcache sqlite3_pcache; ** 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: ** ** -**
createFlagExpected Behaviour -**
0NULL should be returned. No new cache entry is created. -**
1If 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. -**
2If 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. +**
createFlag Behaviour when page is not already in cache +**
0 Do not allocate a new page. Return NULL. +**
1 Allocate a new page if it easy and convenient to do so. +** Otherwise return NULL. +**
2 Make every effort to allocate a new page. Only return +** NULL if allocating a new page is effectively impossible. **
** +** 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