Improvements to the SQLITE_CONFIG_PAGECACHE documentation. Enhance the

command-line shell to be able to take advantage of the full range of
SQLITE_CONFIG_PAGECACHE capabilities, such as setting pMem==NULL and N<0.

FossilOrigin-Name: 2518d5c971c4b32d9227b3bb7259162e3e27b00b

manifest

@@ -1,5 +1,5 @@
-C Improved\soutput\sformatting\sfor\s"PRAGMA\sparser_trace=ON;".
+C Improvements\sto\sthe\sSQLITE_CONFIG_PAGECACHE\sdocumentation.\s\sEnhance\sthe\ncommand-line\sshell\sto\sbe\sable\sto\stake\sadvantage\sof\sthe\sfull\srange\sof\nSQLITE_CONFIG_PAGECACHE\scapabilities,\ssuch\sas\ssetting\spMem==NULL\sand\sN<0.
-D 2015-11-10T14:51:22.311
+D 2015-11-11T15:28:52.898
 F Makefile.in d828db6afa6c1fa060d01e33e4674408df1942a1
 F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
 F Makefile.msc e928e68168df69b353300ac87c10105206653a03
@@ -340,8 +340,8 @@ F src/random.c ba2679f80ec82c4190062d756f22d0c358180696
 F src/resolve.c 1954a0f01bf65d78d7d559aea3d5c67f33376d91
 F src/rowset.c eccf6af6d620aaa4579bd3b72c1b6395d9e9fa1e
 F src/select.c 00a2a10d4298a685d0eeb05b09ef018a2bd81bf8
-F src/shell.c d25df04168d6ba5a4fa05bdbf859df667f9eb621
+F src/shell.c acefb4593a9bf0338a757c968f1f1bb05690d830
-F src/sqlite.h.in 3cfc86c55e57c63d86b9e1e92869e2bfb162ca8e
+F src/sqlite.h.in 278df052181b0e5b0bcdb2089ff09596ae9eca15
 F src/sqlite3.rc 992c9f5fb8285ae285d6be28240a7e8d3a7f2bad
 F src/sqlite3ext.h 4b66e3e3435da4b4c8c83696d0349f0c503b3924
 F src/sqliteInt.h bc6d24460fe544323517630b1e20539146379077
@@ -1402,7 +1402,7 @@ F tool/vdbe_profile.tcl 246d0da094856d72d2c12efec03250d71639d19f
 F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4
 F tool/warnings.sh 48bd54594752d5be3337f12c72f28d2080cb630b
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 1e4849911e3eed65eabee18fdee63bab4faae57a
+P e43e1171fd7837a08069dc25df4eac14db1c2afe
-R 09ae4147f1c84fb513e1a92470f43128
+R 9a1d72f8baac116c36385e92e48c0378
 U drh
-Z 86e43e17960e74008de165832cc2a68a
+Z 9d52ec874b9a01b7b0eb1dab69dbb993

manifest.uuid

@@ -1 +1 @@
-e43e1171fd7837a08069dc25df4eac14db1c2afe
+2518d5c971c4b32d9227b3bb7259162e3e27b00b

src/shell.c

@@ -4601,10 +4601,10 @@ int SQLITE_CDECL main(int argc, char **argv){
       int n, sz;
       sz = (int)integerValue(cmdline_option_value(argc,argv,++i));
       if( sz>70000 ) sz = 70000;
-      if( sz<800 ) sz = 800;
+      if( sz<0 ) sz = 0;
       n = (int)integerValue(cmdline_option_value(argc,argv,++i));
-      if( n<10 ) n = 10;
+      sqlite3_config(SQLITE_CONFIG_PAGECACHE,
-      sqlite3_config(SQLITE_CONFIG_PAGECACHE, malloc(n*sz+1), sz, n);
+                    (n>0 && sz>0) ? malloc(n*sz) : 0, sz, n);
       data.shellFlgs |= SHFLG_Pagecache;
     }else if( strcmp(z,"-lookaside")==0 ){
       int n, sz;

src/sqlite.h.in

@@ -1599,29 +1599,34 @@ struct sqlite3_mem_methods {
 ** </dd>
 **
 ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
-** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a static memory buffer
+** <dd> ^The SQLITE_CONFIG_PAGECACHE option a memory pool
 ** that SQLite can use for the database page cache with the default page
 ** cache implementation.  
-** This configuration should not be used if an application-define page
+** This configuration option is a no-op if an application-define page
-** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2]
+** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
-** configuration option.
 ** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
-** 8-byte aligned
+** 8-byte aligned memory (pMem), the size of each page cache line (sz),
-** memory, the size of each page buffer (sz), and the number of pages (N).
+** and the number of cache lines (N).
 ** The sz argument should be the size of the largest database page
 ** (a power of two between 512 and 65536) plus some extra bytes for each
 ** page header.  ^The number of extra bytes needed by the page header
-** can be determined using the [SQLITE_CONFIG_PCACHE_HDRSZ] option 
+** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
-** to [sqlite3_config()].
 ** ^It is harmless, apart from the wasted memory,
-** for the sz parameter to be larger than necessary.  The first
+** for the sz parameter to be larger than necessary.  The pMem
-** argument should pointer to an 8-byte aligned block of memory that
+** argument must be either a NULL pointer or a pointer to an 8-byte
-** is at least sz*N bytes of memory, otherwise subsequent behavior is
+** aligned block of memory of at least sz*N bytes, otherwise
-** undefined.
+** subsequent behavior is undefined.
-** ^SQLite will use the memory provided by the first argument to satisfy its
+** ^When pMem is not NULL, SQLite will strive to use the memory provided
-** memory needs for the first N pages that it adds to cache.  ^If additional
+** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
-** page cache memory is needed beyond what is provided by this option, then
+** a page cache line is larger than sz bytes or if all of the pMem buffer
-** SQLite goes to [sqlite3_malloc()] for the additional storage space.</dd>
+** is exhausted.
+** ^If pMem is NULL and N is non-zero, then each database connection
+** does an initial bulk allocation for page cache memory
+** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
+** of -1024*N bytes if N is negative, . ^If additional
+** page cache memory is needed beyond what is provided by the initial
+** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
+** additional cache line. </dd>
 **
 ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
 ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer