From: drh Date: Thu, 9 Sep 2010 18:25:34 +0000 (+0000) Subject: Further updates to the sqlite3_pcache_methods documentation, plus the addition X-Git-Tag: experimental~51 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f759bb83d48b354f6ba189ec2abd561ab0821ec8;p=thirdparty%2Fsqlite.git Further updates to the sqlite3_pcache_methods documentation, plus the addition of a few evidence marks related to pcache. FossilOrigin-Name: 34edb54bb03ad4e54f2e4de12d767e6fa8822ba4 --- diff --git a/manifest b/manifest index 0b06040fd3..611efc6144 100644 --- a/manifest +++ b/manifest @@ -1,8 +1,8 @@ -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 -C Make\ssure\smemory\sstatistics\sare\senabled\sfor\sthe\sdbstatus.test\sscript. -D 2010-09-09T17:43:07 +C Further\supdates\sto\sthe\ssqlite3_pcache_methods\sdocumentation,\splus\sthe\saddition\nof\sa\sfew\sevidence\smarks\srelated\sto\spcache. +D 2010-09-09T18:25:34 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f F Makefile.in c599a15d268b1db2aeadea19df2adc3bf2eb6bee F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23 @@ -142,7 +142,7 @@ F src/journal.c 552839e54d1bf76fb8f7abe51868b66acacf6a0e F src/legacy.c a199d7683d60cef73089e892409113e69c23a99f F src/lempar.c 7f026423f4d71d989e719a743f98a1cbd4e6d99e F src/loadext.c 6d422ea91cf3d2d00408c5a8f2391cd458da85f8 -F src/main.c ca8eadcf620f0b48fdf33d0bb63115214e798bc0 +F src/main.c da74b2269470d97a702d2956eeeb691a5e3a68c3 F src/malloc.c e0e9ca16a90215e2f0b53e7f5cc17abe01fbe34a F src/mem0.c 6a55ebe57c46ca1a7d98da93aaa07f99f1059645 F src/mem1.c 00bd8265c81abb665c48fea1e0c234eb3b922206 @@ -166,7 +166,7 @@ F src/os_win.c 2f90f7bdec714fad51cd31b4ecad3cc1b4bb5aad F src/pager.c 51d77a9df463f77bf214f32bb2dbc2d0da41fc3e F src/pager.h 8167a1e720d0b7a2790079007128e594010220ad F src/parse.y 12b7ebd61ea54f0e1b1083ff69cc2c8ce9353d58 -F src/pcache.c 1e9aa2dbc0845b52e1b51cc39753b6d1e041cb07 +F src/pcache.c 09d38c44ab275db581f7a2f6ff8b9bc7f8c0faaa F src/pcache.h c683390d50f856d4cd8e24342ae62027d1bb6050 F src/pcache1.c d090673e7489940dfaddf3fb72ab550c409b2744 F src/pragma.c 8b24ce00a93de345b6c3bd1e1e2cfba9f63d2325 @@ -177,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 b89e75082482613994267333e7c0be1b5e33a788 +F src/sqlite.h.in 0b4284c09f25406bfb2bf93784fae02cbd737773 F src/sqlite3ext.h 69dfb8116af51b84a029cddb3b35062354270c89 F src/sqliteInt.h 81343db96497aebf81dff9c695dfd29699b377b3 F src/sqliteLimit.h a17dcd3fb775d63b64a43a55c54cb282f9726f44 @@ -860,14 +860,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f -P b21425c4045883fffa46af632e77cf708d862927 -R a1d373214123358a3dad3307851ff252 +P 35b943a0fc153341f5299218f2884245c63071b3 +R 72a49807318a0aed719af9a7dff10a58 U drh -Z 95a23b45d32950a2a26c7cd0bd94c524 +Z 9fcfa7841c872e40f68648619ac0762d -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) -iD8DBQFMiRyuoxKgR168RlERAuCgAJ4+3jm02AUbAo4FwMxIbZz7scdwDQCcDSEr -DoAj6hJsCkQ0Gg+SDJC+OJU= -=v8JN +iD8DBQFMiSagoxKgR168RlERAnM1AJ94lqdlkTQroa3O3qMAPMnDXNOdmACdFg8W +4y+J85fxplS7D14pk9iNPds= +=R8Ch -----END PGP SIGNATURE----- diff --git a/manifest.uuid b/manifest.uuid index e40eb37f94..1f479d1200 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -35b943a0fc153341f5299218f2884245c63071b3 \ No newline at end of file +34edb54bb03ad4e54f2e4de12d767e6fa8822ba4 \ No newline at end of file diff --git a/src/main.c b/src/main.c index 92069a427d..3b1ddaf9cc 100644 --- a/src/main.c +++ b/src/main.c @@ -173,6 +173,13 @@ int sqlite3_initialize(void){ ** sqlite3_initialize(). The recursive calls normally come through ** sqlite3_os_init() when it invokes sqlite3_vfs_register(), but other ** recursive calls might also be possible. + ** + ** IMPLEMENTATION-OF: R-00140-37445 SQLite automatically serializes calls + ** to the xInit method, so the xInit method need not be threadsafe. + ** + ** The following mutex is what serializes access to the appdef pcache xInit + ** methods. The sqlite3_pcache_methods.xInit() all is embedded in the + ** call to sqlite3PcacheInitialize(). */ sqlite3_mutex_enter(sqlite3GlobalConfig.pInitMutex); if( sqlite3GlobalConfig.isInit==0 && sqlite3GlobalConfig.inProgress==0 ){ diff --git a/src/pcache.c b/src/pcache.c index 23ea0a7c7d..242f3071d9 100644 --- a/src/pcache.c +++ b/src/pcache.c @@ -142,12 +142,16 @@ static void pcacheUnpin(PgHdr *p){ */ int sqlite3PcacheInitialize(void){ if( sqlite3GlobalConfig.pcache.xInit==0 ){ + /* IMPLEMENTATION-OF: R-26801-64137 If the xInit() method is NULL, then the + ** built-in default page cache is used instead of the application defined + ** page cache. */ sqlite3PCacheSetDefault(); } return sqlite3GlobalConfig.pcache.xInit(sqlite3GlobalConfig.pcache.pArg); } void sqlite3PcacheShutdown(void){ if( sqlite3GlobalConfig.pcache.xShutdown ){ + /* IMPLEMENTATION-OF: R-26000-56589 The xShutdown() method may be NULL. */ sqlite3GlobalConfig.pcache.xShutdown(sqlite3GlobalConfig.pcache.pArg); } } diff --git a/src/sqlite.h.in b/src/sqlite.h.in index f3b81ee00f..0fda216235 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -5441,9 +5441,9 @@ typedef struct sqlite3_pcache sqlite3_pcache; ** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^ ** 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.)^ +** ^(If the xInit() method is NULL, then the +** built-in default page cache is used instead of the application defined +** page cache.)^ ** ** ^The xShutdown() method is called by [sqlite3_shutdown()]. ** It can be used to clean up @@ -5488,21 +5488,21 @@ typedef struct sqlite3_pcache sqlite3_pcache; ** parameter, the implementation is not required to do anything with this ** value; it is advisory only. ** -** ^The xPagecount() method must return the number of pages currently +** The xPagecount() method must return the number of pages currently ** stored in the cache, both pinned and unpinned. ** -** ^The xFetch() method locates a page in the cache and returns a pointer to +** 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 +** A "page", in this context, means 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". ** -** ^If the requested page is already in the page cache, then the page cache +** 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: +** intact. If the requested page is not already in the cache, then the +** behavior of the cache implementation should use the value of the createFlag +** parameter to help it determined what action to take: ** ** **
createFlag Behaviour when page is not already in cache @@ -5511,37 +5511,35 @@ typedef struct sqlite3_pcache sqlite3_pcache; ** 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 may +** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite +** will only use a createFlag of 2 after a prior call with a createFlag of 1 +** failed.)^ In between the to xFetch() calls, 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 may be invoked again with -** a createFlag of 2. +** pinned pages to disk and synching the operating system disk cache. ** ** ^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 +** as its second argument. If the third parameter, discard, is non-zero, +** then the page must be evicted from the cache. +** ^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 +** page cache implementation. ^The page cache implementation ** may choose to evict unpinned pages at any time. ** -** ^(The cache must not 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().)^ +** to xFetch(). ** -** ^The xRekey() method is used to change the key value associated with the -** page passed as the second argument. ^If the cache +** The xRekey() method is used to change the key value associated with the +** 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. ** -** ^When SQLite calls the xTruncate() method, the cache must discard all +** When SQLite calls the xTruncate() method, the cache must discard all ** existing cache entries with page numbers (keys) greater than or equal -** to the value of the iLimit parameter passed to xTruncate(). ^If any +** to the value of the iLimit parameter passed to xTruncate(). If any ** of these pages are pinned, they are implicitly unpinned, meaning that ** they can be safely discarded. **