/ Check-in [b0810ac1]
Login

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

Overview
Comment:Clarify the expectations for the behavior of the xFetch method on the sqlite3_pcache_methods object for the case when the key is zero.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | pcache1-zero-page
Files: files | file ages | folders
SHA1: b0810ac1b22226a0ffcf73868779d7e98b5d8263
User & Date: drh 2016-12-30 13:55:50
Context
2016-12-30
13:55
Clarify the expectations for the behavior of the xFetch method on the sqlite3_pcache_methods object for the case when the key is zero. Closed-Leaf check-in: b0810ac1 user: drh tags: pcache1-zero-page
13:40
Improved detection of zero page numbers in the page cache. check-in: 5550e815 user: drh tags: pcache1-zero-page
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  7211   7211   ** The pBuf element of the returned sqlite3_pcache_page object will be a
  7212   7212   ** pointer to a buffer of szPage bytes used to store the content of a 
  7213   7213   ** single database page.  The pExtra element of sqlite3_pcache_page will be
  7214   7214   ** a pointer to the szExtra bytes of extra storage that SQLite has requested
  7215   7215   ** for each entry in the page cache.
  7216   7216   **
  7217   7217   ** The page to be fetched is determined by the key. ^The minimum key value
  7218         -** is 1.  After it has been retrieved using xFetch, the page is considered
         7218  +** is 1.  The xFetch() method must return NULL if passed a key of 0.
         7219  +** After it has been retrieved using xFetch, the page is considered
  7219   7220   ** to be "pinned".
  7220   7221   **
  7221   7222   ** If the requested page is already in the page cache, then the page cache
  7222   7223   ** implementation must return a pointer to the page buffer with its content
  7223   7224   ** intact.  If the requested page is not already in the cache, then the
  7224   7225   ** cache implementation should use the value of the createFlag
  7225   7226   ** parameter to help it determined what action to take:
  7226   7227   **
  7227   7228   ** <table border=1 width=85% align=center>
  7228   7229   ** <tr><th> createFlag <th> Behavior when page is not already in cache
  7229   7230   ** <tr><td> 0 <td> Do not allocate a new page.  Return NULL.
  7230         -** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
  7231         -**                 Otherwise return NULL.
         7231  +** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so
         7232  +**                 and the key is not zero.  Otherwise return NULL.
  7232   7233   ** <tr><td> 2 <td> Make every effort to allocate a new page.  Only return
  7233         -**                 NULL if allocating a new page is effectively impossible.
         7234  +**                 NULL if the key is zero or if allocating a new page is 
         7235  +**                 effectively impossible.
  7234   7236   ** </table>
  7235   7237   **
  7236   7238   ** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1.  SQLite
  7237   7239   ** will only use a createFlag of 2 after a prior call with a createFlag of 1
  7238   7240   ** failed.)^  In between the to xFetch() calls, SQLite may
  7239   7241   ** attempt to unpin one or more cache pages by spilling the content of
  7240   7242   ** pinned pages to disk and synching the operating system disk cache.