/ Check-in [34edb54b]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Further updates to the sqlite3_pcache_methods documentation, plus the addition of a few evidence marks related to pcache.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 34edb54bb03ad4e54f2e4de12d767e6fa8822ba4
User & Date: drh 2010-09-09 18:25:34
Context
2010-09-09
19:02
Add test cases to e_select.test. check-in: 5e73f7b2 user: dan tags: trunk
18:25
Further updates to the sqlite3_pcache_methods documentation, plus the addition of a few evidence marks related to pcache. check-in: 34edb54b user: drh tags: trunk
17:43
Make sure memory statistics are enabled for the dbstatus.test script. check-in: 35b943a0 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/main.c.

   169    169     }
   170    170   
   171    171     /* Do the rest of the initialization under the recursive mutex so
   172    172     ** that we will be able to handle recursive calls into
   173    173     ** sqlite3_initialize().  The recursive calls normally come through
   174    174     ** sqlite3_os_init() when it invokes sqlite3_vfs_register(), but other
   175    175     ** recursive calls might also be possible.
          176  +  **
          177  +  ** IMPLEMENTATION-OF: R-00140-37445 SQLite automatically serializes calls
          178  +  ** to the xInit method, so the xInit method need not be threadsafe.
          179  +  **
          180  +  ** The following mutex is what serializes access to the appdef pcache xInit
          181  +  ** methods.  The sqlite3_pcache_methods.xInit() all is embedded in the
          182  +  ** call to sqlite3PcacheInitialize().
   176    183     */
   177    184     sqlite3_mutex_enter(sqlite3GlobalConfig.pInitMutex);
   178    185     if( sqlite3GlobalConfig.isInit==0 && sqlite3GlobalConfig.inProgress==0 ){
   179    186       FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
   180    187       sqlite3GlobalConfig.inProgress = 1;
   181    188       memset(pHash, 0, sizeof(sqlite3GlobalFunctions));
   182    189       sqlite3RegisterGlobalFunctions();

Changes to src/pcache.c.

   138    138   /*************************************************** General Interfaces ******
   139    139   **
   140    140   ** Initialize and shutdown the page cache subsystem. Neither of these 
   141    141   ** functions are threadsafe.
   142    142   */
   143    143   int sqlite3PcacheInitialize(void){
   144    144     if( sqlite3GlobalConfig.pcache.xInit==0 ){
          145  +    /* IMPLEMENTATION-OF: R-26801-64137 If the xInit() method is NULL, then the
          146  +    ** built-in default page cache is used instead of the application defined
          147  +    ** page cache. */
   145    148       sqlite3PCacheSetDefault();
   146    149     }
   147    150     return sqlite3GlobalConfig.pcache.xInit(sqlite3GlobalConfig.pcache.pArg);
   148    151   }
   149    152   void sqlite3PcacheShutdown(void){
   150    153     if( sqlite3GlobalConfig.pcache.xShutdown ){
          154  +    /* IMPLEMENTATION-OF: R-26000-56589 The xShutdown() method may be NULL. */
   151    155       sqlite3GlobalConfig.pcache.xShutdown(sqlite3GlobalConfig.pcache.pArg);
   152    156     }
   153    157   }
   154    158   
   155    159   /*
   156    160   ** Return the size in bytes of a PCache object.
   157    161   */

Changes to src/sqlite.h.in.

  5437   5437   **
  5438   5438   ** ^(The xInit() method is called once for each effective 
  5439   5439   ** call to [sqlite3_initialize()])^
  5440   5440   ** (usually only once during the lifetime of the process). ^(The xInit()
  5441   5441   ** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
  5442   5442   ** The intent of the xInit() method is to set up global data structures 
  5443   5443   ** required by the custom page cache implementation. 
  5444         -** ^(If the xInit() method is NULL, then the call to
  5445         -** [sqlite3_config]([SQLITE_CONFIG_PCACHE],...) will install the
  5446         -** built-in default page cache.)^
         5444  +** ^(If the xInit() method is NULL, then the 
         5445  +** built-in default page cache is used instead of the application defined
         5446  +** page cache.)^
  5447   5447   **
  5448   5448   ** ^The xShutdown() method is called by [sqlite3_shutdown()].
  5449   5449   ** It can be used to clean up 
  5450   5450   ** any outstanding resources before process shutdown, if required.
  5451   5451   ** ^The xShutdown() method may be NULL.
  5452   5452   **
  5453   5453   ** ^SQLite automatically serializes calls to the xInit method,
................................................................................
  5484   5484   ** ^(The xCachesize() method may be called at any time by SQLite to set the
  5485   5485   ** suggested maximum cache-size (number of pages stored by) the cache
  5486   5486   ** instance passed as the first argument. This is the value configured using
  5487   5487   ** the SQLite "[PRAGMA cache_size]" command.)^  As with the bPurgeable
  5488   5488   ** parameter, the implementation is not required to do anything with this
  5489   5489   ** value; it is advisory only.
  5490   5490   **
  5491         -** ^The xPagecount() method must return the number of pages currently
         5491  +** The xPagecount() method must return the number of pages currently
  5492   5492   ** stored in the cache, both pinned and unpinned.
  5493   5493   ** 
  5494         -** ^The xFetch() method locates a page in the cache and returns a pointer to 
         5494  +** The xFetch() method locates a page in the cache and returns a pointer to 
  5495   5495   ** the page, or a NULL pointer.
  5496         -** ^A 'page', in this context, is a buffer of szPage bytes aligned at an
  5497         -** 8-byte boundary. ^The page to be fetched is determined by the key. ^The
  5498         -** mimimum key value is 1.  ^After it has been retrieved using xFetch, the page 
         5496  +** A "page", in this context, means a buffer of szPage bytes aligned at an
         5497  +** 8-byte boundary. The page to be fetched is determined by the key. ^The
         5498  +** mimimum key value is 1.  After it has been retrieved using xFetch, the page 
  5499   5499   ** is considered to be "pinned".
  5500   5500   **
  5501         -** ^If the requested page is already in the page cache, then the page cache
         5501  +** If the requested page is already in the page cache, then the page cache
  5502   5502   ** implementation must return a pointer to the page buffer with its content
  5503         -** intact.  ^(If the requested page is not already in the cache, then the
  5504         -** behavior of the cache implementation is determined by the value of the
  5505         -** createFlag parameter passed to xFetch, according to the following table:
         5503  +** intact.  If the requested page is not already in the cache, then the
         5504  +** behavior of the cache implementation should use the value of the createFlag
         5505  +** parameter to help it determined what action to take:
  5506   5506   **
  5507   5507   ** <table border=1 width=85% align=center>
  5508   5508   ** <tr><th> createFlag <th> Behaviour when page is not already in cache
  5509   5509   ** <tr><td> 0 <td> Do not allocate a new page.  Return NULL.
  5510   5510   ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
  5511   5511   **                 Otherwise return NULL.
  5512   5512   ** <tr><td> 2 <td> Make every effort to allocate a new page.  Only return
  5513   5513   **                 NULL if allocating a new page is effectively impossible.
  5514         -** </table>)^
         5514  +** </table>
  5515   5515   **
  5516         -** SQLite will normally invoke xFetch() with a createFlag of 0 or 1.  If
  5517         -** a call to xFetch() with createFlag==1 returns NULL, then SQLite may
         5516  +** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1.  SQLite
         5517  +** will only use a createFlag of 2 after a prior call with a createFlag of 1
         5518  +** failed.)^  In between the to xFetch() calls, SQLite may
  5518   5519   ** attempt to unpin one or more cache pages by spilling the content of
  5519         -** pinned pages to disk and synching the operating system disk cache. After
  5520         -** attempting to unpin pages, the xFetch() method may be invoked again with
  5521         -** a createFlag of 2.
         5520  +** pinned pages to disk and synching the operating system disk cache.
  5522   5521   **
  5523   5522   ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
  5524         -** as its second argument. ^(If the third parameter, discard, is non-zero,
  5525         -** then the page should be evicted from the cache. In this case SQLite 
  5526         -** assumes that the next time the page is retrieved from the cache using
  5527         -** the xFetch() method, it will be zeroed.)^ If the discard parameter is
         5523  +** as its second argument.  If the third parameter, discard, is non-zero,
         5524  +** then the page must be evicted from the cache.
         5525  +** ^If the discard parameter is
  5528   5526   ** zero, then the page may be discarded or retained at the discretion of
  5529         -** page cache implementation. The page cache implementation
         5527  +** page cache implementation. ^The page cache implementation
  5530   5528   ** may choose to evict unpinned pages at any time.
  5531   5529   **
  5532         -** ^(The cache must not perform any reference counting. A single 
         5530  +** The cache must not perform any reference counting. A single 
  5533   5531   ** call to xUnpin() unpins the page regardless of the number of prior calls 
  5534         -** to xFetch().)^
         5532  +** to xFetch().
  5535   5533   **
  5536         -** ^The xRekey() method is used to change the key value associated with the
  5537         -** page passed as the second argument. ^If the cache
         5534  +** The xRekey() method is used to change the key value associated with the
         5535  +** page passed as the second argument. If the cache
  5538   5536   ** previously contains an entry associated with newKey, it must be
  5539   5537   ** discarded. ^Any prior cache entry associated with newKey is guaranteed not
  5540   5538   ** to be pinned.
  5541   5539   **
  5542         -** ^When SQLite calls the xTruncate() method, the cache must discard all
         5540  +** When SQLite calls the xTruncate() method, the cache must discard all
  5543   5541   ** existing cache entries with page numbers (keys) greater than or equal
  5544         -** to the value of the iLimit parameter passed to xTruncate(). ^If any
         5542  +** to the value of the iLimit parameter passed to xTruncate(). If any
  5545   5543   ** of these pages are pinned, they are implicitly unpinned, meaning that
  5546   5544   ** they can be safely discarded.
  5547   5545   **
  5548   5546   ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
  5549   5547   ** All resources associated with the specified cache should be freed. ^After
  5550   5548   ** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
  5551   5549   ** handle invalid, and will not use it with any other sqlite3_pcache_methods