Update comments on the free-page allocator to accurately reflect the

latest implementation.  Add new asserts to the free-page allocator.

FossilOrigin-Name: 9a135e37b696b8544da8dbddf9d1041b8fa6f1c2

manifest

@@ -1,5 +1,5 @@
-C Complete\sthe\sinitialization\sof\sthe\sloadable\sextension\sthunk\stable.\s\sAlso\nfix\sother\s(harmless)\scompiler\swarnings.
+C Update\scomments\son\sthe\sfree-page\sallocator\sto\saccurately\sreflect\sthe\nlatest\simplementation.\s\sAdd\snew\sasserts\sto\sthe\sfree-page\sallocator.
-D 2013-03-01T23:40:26.913
+D 2013-03-02T03:25:55.218
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in a48faa9e7dd7d556d84f5456eabe5825dd8a6282
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -121,7 +121,7 @@ F src/auth.c 523da7fb4979469955d822ff9298352d6b31de34
 F src/backup.c b2cac9f7993f3f9588827b824b1501d0c820fa68
 F src/bitvec.c 26675fe8e431dc555e6f2d0e11e651d172234aa1
 F src/btmutex.c 976f45a12e37293e32cae0281b15a21d48a8aaa7
-F src/btree.c cbad71970cfadfa342fc137ca5e319f98b2d0da1
+F src/btree.c ea4cc870674e608cd9349798d6f7811feeb85643
 F src/btree.h 3ad7964d6c5b1c7bff569aab6adfa075f8bf06cd
 F src/btreeInt.h eecc84f02375b2bb7a44abbcbbe3747dde73edb2
 F src/build.c 375e5df716e03b9343c5e1211be3b24e6d6dff05
@@ -1036,7 +1036,7 @@ F tool/vdbe-compress.tcl f12c884766bd14277f4fcedcae07078011717381
 F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4
 F tool/warnings.sh fbc018d67fd7395f440c28f33ef0f94420226381
 F tool/win/sqlite.vsix 97894c2790eda7b5bce3cc79cb2a8ec2fde9b3ac
-P 6b2838336a31e34c540210ccc9c934d4ba94757c
+P 780d06c5e54590f677f993fa9c313989c2eab8c7
-R db69dd670ef335759c7475908d848a42
+R f5753609ff29532bc332844f7d251f42
 U drh
-Z d35d3652e81b05a9c2009fdff0b4ddbd
+Z ee29f611b55f3013b3ce8fc0c9bc38da

manifest.uuid

@@ -1 +1 @@
-780d06c5e54590f677f993fa9c313989c2eab8c7
+9a135e37b696b8544da8dbddf9d1041b8fa6f1c2

src/btree.c

@@ -4875,21 +4875,23 @@ int sqlite3BtreePrevious(BtCursor *pCur, int *pRes){
 ** an error.  *ppPage and *pPgno are undefined in the event of an error.
 ** Do not invoke sqlite3PagerUnref() on *ppPage if an error is returned.
 **
-** If the "nearby" parameter is not 0, then a (feeble) effort is made to 
+** If the "nearby" parameter is not 0, then an effort is made to 
 ** locate a page close to the page number "nearby".  This can be used in an
 ** attempt to keep related pages close to each other in the database file,
 ** which in turn can make database access faster.
 **
-** If the "exact" parameter is not 0, and the page-number nearby exists 
+** If the eMode parameter is BTALLOC_EXACT and the nearby page exists
-** anywhere on the free-list, then it is guarenteed to be returned. This
+** anywhere on the free-list, then it is guaranteed to be returned.  If
-** is only used by auto-vacuum databases when allocating a new table.
+** eMode is BTALLOC_LT then the page returned will be less than or equal
+** to nearby if any such page exists.  If eMode is BTALLOC_ANY then there
+** are no restrictions on which page is returned.
 */
 static int allocateBtreePage(
-  BtShared *pBt, 
+  BtShared *pBt,         /* The btree */
-  MemPage **ppPage, 
+  MemPage **ppPage,      /* Store pointer to the allocated page here */
-  Pgno *pPgno, 
+  Pgno *pPgno,           /* Store the page number here */
-  Pgno nearby,
+  Pgno nearby,           /* Search for a page near this one */
-  u8 eMode
+  u8 eMode               /* BTALLOC_EXACT, BTALLOC_LT, or BTALLOC_ANY */
 ){
   MemPage *pPage1;
   int rc;
@@ -4900,6 +4902,7 @@ static int allocateBtreePage(
   Pgno mxPage;     /* Total size of the database file */
 
   assert( sqlite3_mutex_held(pBt->mutex) );
+  assert( eMode==BTALLOC_ANY || (nearby>0 && pBt->autoVacuum) );
   pPage1 = pBt->pPage1;
   mxPage = btreePagecount(pBt);
   n = get4byte(&pPage1->aData[36]);
@@ -4912,7 +4915,7 @@ static int allocateBtreePage(
     Pgno iTrunk;
     u8 searchList = 0; /* If the free-list must be searched for 'nearby' */
     
-    /* If the 'exact' parameter was true and a query of the pointer-map
+    /* If eMode==BTALLOC_EXACT and a query of the pointer-map
     ** shows that the page 'nearby' is somewhere on the free-list, then
     ** the entire-list will be searched for that page.
     */
@@ -4942,7 +4945,8 @@ static int allocateBtreePage(
 
     /* The code within this loop is run only once if the 'searchList' variable
     ** is not true. Otherwise, it runs once for each trunk-page on the
-    ** free-list until the page 'nearby' is located.
+    ** free-list until the page 'nearby' is located (eMode==BTALLOC_EXACT)
+    ** or until a page less than 'nearby' is located (eMode==BTALLOC_LT)
     */
     do {
       pPrevTrunk = pTrunk;