From: drh Date: Thu, 9 Sep 2010 15:48:20 +0000 (+0000) Subject: Updates to the sqlite3_pcache_methods documentation. X-Git-Tag: experimental~53 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=cee8296af2137dcc1fc684c698ab3e7033607419;p=thirdparty%2Fsqlite.git Updates to the sqlite3_pcache_methods documentation. FossilOrigin-Name: b21425c4045883fffa46af632e77cf708d862927 --- diff --git a/manifest b/manifest index 9a37503d1f..7d660792ee 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,8 @@ -C Add\sWHERE\sclause\stests\sto\se_select.test. -D 2010-09-09T11:33:09 +-----BEGIN PGP SIGNED MESSAGE----- +Hash: SHA1 + +C Updates\sto\sthe\ssqlite3_pcache_methods\sdocumentation. +D 2010-09-09T15:48:21 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f F Makefile.in c599a15d268b1db2aeadea19df2adc3bf2eb6bee F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23 @@ -174,7 +177,7 @@ F src/resolve.c 1c0f32b64f8e3f555fe1f732f9d6f501a7f05706 F src/rowset.c 69afa95a97c524ba6faf3805e717b5b7ae85a697 F src/select.c b0b124781474e4e0c8f64022875e5e2009e13443 F src/shell.c 8517fc1f9c59ae4007e6cc8b9af91ab231ea2056 -F src/sqlite.h.in 0e98e780993e6cf185bd228f275b959a5aef86c6 +F src/sqlite.h.in b89e75082482613994267333e7c0be1b5e33a788 F src/sqlite3ext.h 69dfb8116af51b84a029cddb3b35062354270c89 F src/sqliteInt.h 81343db96497aebf81dff9c695dfd29699b377b3 F src/sqliteLimit.h a17dcd3fb775d63b64a43a55c54cb282f9726f44 @@ -857,7 +860,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f -P 2c6b1ca952be9979b8079431c2abad28419b6256 -R b6f7deab8c7be4f26ac3335bb0b04fd4 -U dan -Z 4c41231d0dc68008d74e0f7cc7244851 +P 721b73fa5c5898f6c6d5946e1c70ccd2d0b0dccc +R cbbf9e5140816a6f83795c0332dd3e6e +U drh +Z 74027c69905e1ff505b64e9812591b2f +-----BEGIN PGP SIGNATURE----- +Version: GnuPG v1.4.6 (GNU/Linux) + +iD8DBQFMiQHJoxKgR168RlERAh0tAJ9SNKXu692V3wFNhD4OrbnaYo0azACfaJuF +JHEOkaCKu3GeiSh9DjF/ixg= +=IXg9 +-----END PGP SIGNATURE----- diff --git a/manifest.uuid b/manifest.uuid index 893a4cffbe..518757162c 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -721b73fa5c5898f6c6d5946e1c70ccd2d0b0dccc \ No newline at end of file +b21425c4045883fffa46af632e77cf708d862927 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 7cfcc8dd75..f3b81ee00f 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -4948,7 +4948,7 @@ void sqlite3_mutex_leave(sqlite3_mutex*); ** ** ^The xMutexInit method defined by this structure is invoked as ** part of system initialization by the sqlite3_initialize() function. -** ^The xMutexInit routine is calle by SQLite exactly once for each +** ^The xMutexInit routine is called by SQLite exactly once for each ** effective call to [sqlite3_initialize()]. ** ** ^The xMutexEnd method defined by this structure is invoked as @@ -5416,32 +5416,42 @@ typedef struct sqlite3_pcache sqlite3_pcache; ** ** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can ** register an alternative page cache implementation by passing in an -** instance of the sqlite3_pcache_methods structure.)^ The majority of the -** heap memory used by SQLite is used by the page cache to cache data read -** 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 +** instance of the sqlite3_pcache_methods structure.)^ +** In many applications, most of the heap memory allocated by +** SQLite is used for the page cache. +** By implementing a +** custom page cache using this API, an application can better control +** the amount of memory consumed by SQLite, the way in which ** 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 alternative page cache mechanism is an +** extreme measure that is only needed by the most demanding applications. +** The built-in page cache is recommended for most uses. +** ** ^(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()] +** ^(The xInit() method is called once for each effective +** call to [sqlite3_initialize()])^ ** (usually only once during the lifetime of the process). ^(The xInit() ** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^ -** ^The xInit() method can set up up global structures and/or any mutexes +** The intent of the xInit() method is to set up global data structures ** required by the custom page cache implementation. +** ^(If the xInit() method is NULL, then the call to +** [sqlite3_config]([SQLITE_CONFIG_PCACHE],...) will install the +** built-in default page cache.)^ ** -** ^The xShutdown() method is called from within [sqlite3_shutdown()], -** if the application invokes this API. It can be used to clean up +** ^The xShutdown() method is called by [sqlite3_shutdown()]. +** It can be used to clean up ** any outstanding resources before process shutdown, if required. +** ^The xShutdown() method may be NULL. ** -** ^SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes -** the xInit method, so the xInit method need not be threadsafe. ^The +** ^SQLite automatically serializes calls to the xInit method, +** so the xInit method need not be threadsafe. ^The ** xShutdown method is only called from [sqlite3_shutdown()] so it does ** not need to be threadsafe either. All other methods must be threadsafe ** in multithreaded applications. @@ -5449,40 +5459,43 @@ 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. SQLite -** will typically create one cache instance for each open database file, +** ^SQLite invokes the xCreate() method 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. ^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 +** 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 +** false if it is used for an in-memory database. The cache implementation ** 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 +** ^In other words, calls to xUnpin() on a cache with bPurgeable set to +** false will always have the "discard" flag set to true. +** ^Hence, a cache created with bPurgeable 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 +** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable ** parameter, 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. +** ^The xPagecount() method must return the number of pages currently +** stored in the cache, both pinned and unpinned. ** -** ^The xFetch() method is used to fetch a page and return a pointer to it. +** ^The xFetch() method locates a page in the cache and returns a pointer to +** the page, or a NULL pointer. ** ^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 +** mimimum key value is 1. ^After it has been retrieved using xFetch, the page ** is considered to be "pinned". ** ** ^If the requested page is already in the page cache, then the page cache @@ -5501,27 +5514,28 @@ typedef struct sqlite3_pcache sqlite3_pcache; ** )^ ** ** 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 +** a call to xFetch() with createFlag==1 returns NULL, then SQLite may ** 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 +** attempting to unpin pages, the xFetch() method may 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 +** the xFetch() method, it will be zeroed.)^ If the discard parameter is +** zero, then the page may be discarded or retained at the discretion of +** page cache implementation. The page cache implementation ** may choose to evict unpinned pages at any time. ** -** ^(The cache is not required to perform any reference counting. A single +** ^(The cache must not perform any reference counting. A single ** call to xUnpin() unpins the page regardless of the number of prior calls ** to xFetch().)^ ** ** ^The xRekey() method is used to change the key value associated with the -** page passed as the second argument from oldKey to newKey. ^If the cache -** previously contains an entry associated with newKey, it should be +** page passed as the second argument. ^If the cache +** previously contains an entry associated with newKey, it must be ** discarded. ^Any prior cache entry associated with newKey is guaranteed not ** to be pinned. **