/ Check-in [4da70956]
Login

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

Overview
Comment:Update the API documentation for the new pcache2 interface. Change the order of parameters on the xCreate method of pcache2.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | experimental-pcache
Files: files | file ages | folders
SHA1: 4da7095683ec821414e255419d63a24dbd9d726d
User & Date: drh 2011-11-09 00:06:05
Context
2011-11-09
01:53
For the mem1.c system malloc implementation, use the malloc_usable_size() function if the HAVE_MALLOC_USABLE_SIZE macro is defined. Update autoconf to look for that function when configuring. check-in: 2e8ab3ce user: drh tags: experimental-pcache
00:06
Update the API documentation for the new pcache2 interface. Change the order of parameters on the xCreate method of pcache2. check-in: 4da70956 user: drh tags: experimental-pcache
2011-11-08
20:08
Experimental change to the pcache interface to allow page buffers to be allocated separately from their associated container structures. check-in: c275c9d3 user: dan tags: experimental-pcache
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/pcache.c.

   217    217   
   218    218     /* If the pluggable cache (sqlite3_pcache*) has not been allocated,
   219    219     ** allocate it now.
   220    220     */
   221    221     if( !pCache->pCache && createFlag ){
   222    222       sqlite3_pcache *p;
   223    223       p = sqlite3GlobalConfig.pcache2.xCreate(
   224         -        pCache->szExtra + sizeof(PgHdr), pCache->szPage, pCache->bPurgeable
          224  +        pCache->szPage, pCache->szExtra + sizeof(PgHdr), pCache->bPurgeable
   225    225       );
   226    226       if( !p ){
   227    227         return SQLITE_NOMEM;
   228    228       }
   229    229       sqlite3GlobalConfig.pcache2.xCachesize(p, pCache->nMax);
   230    230       pCache->pCache = p;
   231    231     }

Changes to src/pcache1.c.

    20     20   #include "sqliteInt.h"
    21     21   
    22     22   typedef struct PCache1 PCache1;
    23     23   typedef struct PgHdr1 PgHdr1;
    24     24   typedef struct PgFreeslot PgFreeslot;
    25     25   typedef struct PGroup PGroup;
    26     26   
    27         -
    28     27   /* Each page cache (or PCache) belongs to a PGroup.  A PGroup is a set 
    29     28   ** of one or more PCaches that are able to recycle each others unpinned
    30     29   ** pages when they are under memory pressure.  A PGroup is an instance of
    31     30   ** the following object.
    32     31   **
    33     32   ** This page cache implementation works in one of two modes:
    34     33   **
................................................................................
   550    549   }
   551    550   
   552    551   /*
   553    552   ** Implementation of the sqlite3_pcache.xCreate method.
   554    553   **
   555    554   ** Allocate a new cache.
   556    555   */
   557         -static sqlite3_pcache *pcache1Create(int szExtra, int szPage, int bPurgeable){
          556  +static sqlite3_pcache *pcache1Create(int szPage, int szExtra, int bPurgeable){
   558    557     PCache1 *pCache;      /* The newly created page cache */
   559    558     PGroup *pGroup;       /* The group the new page cache will belong to */
   560    559     int sz;               /* Bytes of memory required to allocate the new cache */
   561    560   
   562    561     /*
   563    562     ** The seperateCache variable is true if each PCache has its own private
   564    563     ** PGroup.  In other words, separateCache is true for mode (1) where no

Changes to src/sqlite.h.in.

  1364   1364   ** scratch memory beyond what is provided by this configuration option, then 
  1365   1365   ** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
  1366   1366   **
  1367   1367   ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
  1368   1368   ** <dd> ^This option specifies a static memory buffer that SQLite can use for
  1369   1369   ** the database page cache with the default page cache implementation.  
  1370   1370   ** This configuration should not be used if an application-define page
  1371         -** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
         1371  +** cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.
  1372   1372   ** There are three arguments to this option: A pointer to 8-byte aligned
  1373   1373   ** memory, the size of each page buffer (sz), and the number of pages (N).
  1374   1374   ** The sz argument should be the size of the largest database page
  1375   1375   ** (a power of two between 512 and 32768) plus a little extra for each
  1376   1376   ** page header.  ^The page header size is 20 to 40 bytes depending on
  1377   1377   ** the host architecture.  ^It is harmless, apart from the wasted memory,
  1378   1378   ** to make sz a little too large.  The first
................................................................................
  1433   1433   ** [database connection].  The first argument is the
  1434   1434   ** size of each lookaside buffer slot and the second is the number of
  1435   1435   ** slots allocated to each database connection.)^  ^(This option sets the
  1436   1436   ** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
  1437   1437   ** verb to [sqlite3_db_config()] can be used to change the lookaside
  1438   1438   ** configuration on individual connections.)^ </dd>
  1439   1439   **
  1440         -** [[SQLITE_CONFIG_PCACHE]] <dt>SQLITE_CONFIG_PCACHE</dt>
         1440  +** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
  1441   1441   ** <dd> ^(This option takes a single argument which is a pointer to
  1442         -** an [sqlite3_pcache_methods] object.  This object specifies the interface
         1442  +** an [sqlite3_pcache_methods2] object.  This object specifies the interface
  1443   1443   ** to a custom page cache implementation.)^  ^SQLite makes a copy of the
  1444   1444   ** object and uses it for page cache memory allocations.</dd>
  1445   1445   **
  1446         -** [[SQLITE_CONFIG_GETPCACHE]] <dt>SQLITE_CONFIG_GETPCACHE</dt>
         1446  +** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
  1447   1447   ** <dd> ^(This option takes a single argument which is a pointer to an
  1448         -** [sqlite3_pcache_methods] object.  SQLite copies of the current
         1448  +** [sqlite3_pcache_methods2] object.  SQLite copies of the current
  1449   1449   ** page cache implementation into that object.)^ </dd>
  1450   1450   **
  1451   1451   ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
  1452   1452   ** <dd> ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
  1453   1453   ** function with a call signature of void(*)(void*,int,const char*), 
  1454   1454   ** and a pointer to void. ^If the function pointer is not NULL, it is
  1455   1455   ** invoked by [sqlite3_log()] to process each logging event.  ^If the
................................................................................
  1474   1474   ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
  1475   1475   ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
  1476   1476   ** connection is opened. If it is globally disabled, filenames are
  1477   1477   ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
  1478   1478   ** database connection is opened. By default, URI handling is globally
  1479   1479   ** disabled. The default value may be changed by compiling with the
  1480   1480   ** [SQLITE_USE_URI] symbol defined.
         1481  +**
         1482  +** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
         1483  +** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFNIG_GETPCACHE
         1484  +** <dd> These options are obsolete and should not be used by new code.
         1485  +** They are retained for backwards compatibility but are now no-ops.
  1481   1486   ** </dl>
  1482   1487   */
  1483   1488   #define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
  1484   1489   #define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
  1485   1490   #define SQLITE_CONFIG_SERIALIZED    3  /* nil */
  1486   1491   #define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
  1487   1492   #define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
................................................................................
  1489   1494   #define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
  1490   1495   #define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
  1491   1496   #define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
  1492   1497   #define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
  1493   1498   #define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
  1494   1499   /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
  1495   1500   #define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
  1496         -#define SQLITE_CONFIG_PCACHE       14  /* sqlite3_pcache_methods* */
  1497         -#define SQLITE_CONFIG_GETPCACHE    15  /* sqlite3_pcache_methods* */
         1501  +#define SQLITE_CONFIG_PCACHE       14  /* no-op */
         1502  +#define SQLITE_CONFIG_GETPCACHE    15  /* no-op */
  1498   1503   #define SQLITE_CONFIG_LOG          16  /* xFunc, void* */
  1499   1504   #define SQLITE_CONFIG_URI          17  /* int */
  1500   1505   #define SQLITE_CONFIG_PCACHE2      18  /* sqlite3_pcache_methods2* */
  1501   1506   #define SQLITE_CONFIG_GETPCACHE2   19  /* sqlite3_pcache_methods2* */
  1502   1507   
  1503   1508   /*
  1504   1509   ** CAPI3REF: Database Connection Configuration Options
................................................................................
  4553   4558   **
  4554   4559   ** <ul>
  4555   4560   ** <li> The soft heap limit is set to zero.
  4556   4561   ** <li> Memory accounting is disabled using a combination of the
  4557   4562   **      [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
  4558   4563   **      the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
  4559   4564   ** <li> An alternative page cache implementation is specified using
  4560         -**      [sqlite3_config]([SQLITE_CONFIG_PCACHE],...).
         4565  +**      [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...).
  4561   4566   ** <li> The page cache allocates from its own memory pool supplied
  4562   4567   **      by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
  4563   4568   **      from the heap.
  4564   4569   ** </ul>)^
  4565   4570   **
  4566   4571   ** Beginning with SQLite version 3.7.3, the soft heap limit is enforced
  4567   4572   ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
................................................................................
  5934   5939   */
  5935   5940   typedef struct sqlite3_pcache sqlite3_pcache;
  5936   5941   
  5937   5942   /*
  5938   5943   ** CAPI3REF: Application Defined Page Cache.
  5939   5944   ** KEYWORDS: {page cache}
  5940   5945   **
  5941         -** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
         5946  +** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE2], ...) interface can
  5942   5947   ** register an alternative page cache implementation by passing in an 
  5943         -** instance of the sqlite3_pcache_methods structure.)^
         5948  +** instance of the sqlite3_pcache_methods2 structure.)^
  5944   5949   ** In many applications, most of the heap memory allocated by 
  5945   5950   ** SQLite is used for the page cache.
  5946   5951   ** By implementing a 
  5947   5952   ** custom page cache using this API, an application can better control
  5948   5953   ** the amount of memory consumed by SQLite, the way in which 
  5949   5954   ** that memory is allocated and released, and the policies used to 
  5950   5955   ** determine exactly which parts of a database file are cached and for 
  5951   5956   ** how long.
  5952   5957   **
  5953   5958   ** The alternative page cache mechanism is an
  5954   5959   ** extreme measure that is only needed by the most demanding applications.
  5955   5960   ** The built-in page cache is recommended for most uses.
  5956   5961   **
  5957         -** ^(The contents of the sqlite3_pcache_methods structure are copied to an
         5962  +** ^(The contents of the sqlite3_pcache_methods2 structure are copied to an
  5958   5963   ** internal buffer by SQLite within the call to [sqlite3_config].  Hence
  5959   5964   ** the application may discard the parameter after the call to
  5960   5965   ** [sqlite3_config()] returns.)^
  5961   5966   **
  5962   5967   ** [[the xInit() page cache method]]
  5963   5968   ** ^(The xInit() method is called once for each effective 
  5964   5969   ** call to [sqlite3_initialize()])^
................................................................................
  5985   5990   ** ^SQLite will never invoke xInit() more than once without an intervening
  5986   5991   ** call to xShutdown().
  5987   5992   **
  5988   5993   ** [[the xCreate() page cache methods]]
  5989   5994   ** ^SQLite invokes the xCreate() method to construct a new cache instance.
  5990   5995   ** SQLite will typically create one cache instance for each open database file,
  5991   5996   ** though this is not guaranteed. ^The
  5992         -** first parameter, szPage, is the size in bytes of the pages that must
  5993         -** be allocated by the cache.  ^szPage will not be a power of two.  ^szPage
  5994         -** will the page size of the database file that is to be cached plus an
  5995         -** increment (here called "R") of less than 250.  SQLite will use the
  5996         -** extra R bytes on each page to store metadata about the underlying
  5997         -** database page on disk.  The value of R depends
         5997  +** parameter parameter, szPage, is the size in bytes of the pages that must
         5998  +** be allocated by the cache.  ^szPage will always a power of two.  ^The
         5999  +** second parameter szExtra is a number of bytes of extra storage 
         6000  +** associated with each page cache entry.  ^The szExtra parameter will
         6001  +** a number less than 250.  SQLite will use the
         6002  +** extra szExtra bytes on each page to store metadata about the underlying
         6003  +** database page on disk.  The value passed into szExtra depends
  5998   6004   ** on the SQLite version, the target platform, and how SQLite was compiled.
  5999         -** ^(R is constant for a particular build of SQLite. Except, there are two
  6000         -** distinct values of R when SQLite is compiled with the proprietary
  6001         -** ZIPVFS extension.)^  ^The second argument to
  6002         -** xCreate(), bPurgeable, is true if the cache being created will
  6003         -** be used to cache database pages of a file stored on disk, or
         6005  +** ^The third argument to xCreate(), bPurgeable, is true if the cache being
         6006  +** created will be used to cache database pages of a file stored on disk, or
  6004   6007   ** false if it is used for an in-memory database. The cache implementation
  6005   6008   ** does not have to do anything special based with the value of bPurgeable;
  6006   6009   ** it is purely advisory.  ^On a cache where bPurgeable is false, SQLite will
  6007   6010   ** never invoke xUnpin() except to deliberately delete a page.
  6008   6011   ** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
  6009   6012   ** false will always have the "discard" flag set to true.  
  6010   6013   ** ^Hence, a cache created with bPurgeable false will
................................................................................
  6020   6023   **
  6021   6024   ** [[the xPagecount() page cache methods]]
  6022   6025   ** The xPagecount() method must return the number of pages currently
  6023   6026   ** stored in the cache, both pinned and unpinned.
  6024   6027   ** 
  6025   6028   ** [[the xFetch() page cache methods]]
  6026   6029   ** The xFetch() method locates a page in the cache and returns a pointer to 
  6027         -** the page, or a NULL pointer.
  6028         -** A "page", in this context, means a buffer of szPage bytes aligned at an
  6029         -** 8-byte boundary. The page to be fetched is determined by the key. ^The
  6030         -** minimum key value is 1.  After it has been retrieved using xFetch, the page 
  6031         -** is considered to be "pinned".
         6030  +** an sqlite3_pcache_page object associated with that page, or a NULL pointer.
         6031  +** The pBuf element of the returned sqlite3_pcache_page object will be a
         6032  +** pointer to a buffer of szPage bytes used to store the content of a 
         6033  +** single database page.  The pExtra element of sqlite3_pcache_page will be
         6034  +** a pointer to the szExtra bytes of extra storage that SQLite has requested
         6035  +** for each entry in the page cache.
         6036  +**
         6037  +** The page to be fetched is determined by the key. ^The minimum key value
         6038  +** is 1.  After it has been retrieved using xFetch, the page is considered
         6039  +** to be "pinned".
  6032   6040   **
  6033   6041   ** If the requested page is already in the page cache, then the page cache
  6034   6042   ** implementation must return a pointer to the page buffer with its content
  6035   6043   ** intact.  If the requested page is not already in the cache, then the
  6036   6044   ** cache implementation should use the value of the createFlag
  6037   6045   ** parameter to help it determined what action to take:
  6038   6046   **
................................................................................
  6080   6088   ** [[the xDestroy() page cache method]]
  6081   6089   ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
  6082   6090   ** All resources associated with the specified cache should be freed. ^After
  6083   6091   ** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
  6084   6092   ** handle invalid, and will not use it with any other sqlite3_pcache_methods
  6085   6093   ** functions.
  6086   6094   */
         6095  +typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
         6096  +typedef struct sqlite3_pcache_page sqlite3_pcache_page;
         6097  +struct sqlite3_pcache_page {
         6098  +  void *pBuf;
         6099  +  void *pExtra;
         6100  +};
         6101  +struct sqlite3_pcache_methods2 {
         6102  +  void *pArg;
         6103  +  int (*xInit)(void*);
         6104  +  void (*xShutdown)(void*);
         6105  +  sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
         6106  +  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
         6107  +  int (*xPagecount)(sqlite3_pcache*);
         6108  +  sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
         6109  +  void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
         6110  +  void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*, 
         6111  +      unsigned oldKey, unsigned newKey);
         6112  +  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
         6113  +  void (*xDestroy)(sqlite3_pcache*);
         6114  +};
         6115  +
         6116  +/*
         6117  +** This is the obsolete pcache_methods object that has now been replaced
         6118  +** by sqlite3_pcache_methods2.  This object is not used by SQLite.  It is
         6119  +** retained in the header file for backwards compatibility only.
         6120  +*/
  6087   6121   typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
  6088   6122   struct sqlite3_pcache_methods {
  6089   6123     void *pArg;
  6090   6124     int (*xInit)(void*);
  6091   6125     void (*xShutdown)(void*);
  6092   6126     sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
  6093   6127     void (*xCachesize)(sqlite3_pcache*, int nCachesize);
................................................................................
  6095   6129     void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  6096   6130     void (*xUnpin)(sqlite3_pcache*, void*, int discard);
  6097   6131     void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
  6098   6132     void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  6099   6133     void (*xDestroy)(sqlite3_pcache*);
  6100   6134   };
  6101   6135   
  6102         -typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
  6103         -typedef struct sqlite3_pcache_page sqlite3_pcache_page;
  6104         -struct sqlite3_pcache_page {
  6105         -  void *pBuf;
  6106         -  void *pExtra;
  6107         -};
  6108         -struct sqlite3_pcache_methods2 {
  6109         -  void *pArg;
  6110         -  int (*xInit)(void*);
  6111         -  void (*xShutdown)(void*);
  6112         -  sqlite3_pcache *(*xCreate)(int szExtra, int szPage, int bPurgeable);
  6113         -  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  6114         -  int (*xPagecount)(sqlite3_pcache*);
  6115         -  sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  6116         -  void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
  6117         -  void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*, 
  6118         -      unsigned oldKey, unsigned newKey);
  6119         -  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  6120         -  void (*xDestroy)(sqlite3_pcache*);
  6121         -};
  6122   6136   
  6123   6137   /*
  6124   6138   ** CAPI3REF: Online Backup Object
  6125   6139   **
  6126   6140   ** The sqlite3_backup object records state information about an ongoing
  6127   6141   ** online backup operation.  ^The sqlite3_backup object is created by
  6128   6142   ** a call to [sqlite3_backup_init()] and is destroyed by a call to

Changes to src/test_pcache.c.

   127    127   }
   128    128   
   129    129   
   130    130   /*
   131    131   ** Allocate a new page cache instance.
   132    132   */
   133    133   static sqlite3_pcache *testpcacheCreate(
   134         -  int szExtra, 
   135    134     int szPage, 
          135  +  int szExtra, 
   136    136     int bPurgeable
   137    137   ){
   138    138     int nMem;
   139    139     char *x;
   140    140     testpcache *p;
   141    141     int i;
   142    142     assert( testpcacheGlobal.pDummy!=0 );