Comment changes that attempt to better explain the behavior of the "seekResult"

field on VdbeCursor objects and the seekResult parameter to
sqlite3BtreeInsert() and the OPFLAG_USESEEKRESULT flag on insert opcodes.
No changes to code.

FossilOrigin-Name: 345b46be75bdf6f9fb7367a6164d89bae11995a6

manifest

@@ -1,5 +1,5 @@
-C Fix\sa\ssimple\scomment\stypo.\s\sNo\schanges\sto\scode.
-D 2016-11-09T16:03:36.041
+C Comment\schanges\sthat\sattempt\sto\sbetter\sexplain\sthe\sbehavior\sof\sthe\s"seekResult"\nfield\son\sVdbeCursor\sobjects\sand\sthe\sseekResult\sparameter\sto\nsqlite3BtreeInsert()\sand\sthe\sOPFLAG_USESEEKRESULT\sflag\son\sinsert\sopcodes.\nNo\schanges\sto\scode.
+D 2016-11-09T20:14:34.342
 F Makefile.in 6fd48ffcf7c2deea7499062d1f3747f986c19678
 F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
 F Makefile.msc e0217f2d35a0448abbe4b066132ae20136e8b408
@@ -330,7 +330,7 @@ F src/auth.c 930b376a9c56998557367e6f7f8aaeac82a2a792
 F src/backup.c faf17e60b43233c214aae6a8179d24503a61e83b
 F src/bitvec.c 3ee4c8b2c94ed3a7377256e18199e6ff5cf33f63
 F src/btmutex.c bc87dd3b062cc26edfe79918de2200ccb8d41e73
-F src/btree.c fa0e4f2656562f18a8aeab5faa5747fc2d6bc497
+F src/btree.c d1a3d691917cb7d67d50318aef990d8f30d172c7
 F src/btree.h 630303068c82a359f6ddf202b205ae927721b090
 F src/btreeInt.h c18b7d2a3494695133e4e60ee36061d37f45d9a5
 F src/build.c 178f16698cbcb43402c343a9413fe22c99ffee21
@@ -454,9 +454,9 @@ F src/update.c 771335a33c958a186b66ef7e349f978d6bb2aac4
 F src/utf.c 699001c79f28e48e9bcdf8a463da029ea660540c
 F src/util.c 3e2da6101888d073e79ecc6af5e0a2f70fa1e498
 F src/vacuum.c 33c174b28886b2faf26e503b5a49a1c01a9b1c16
-F src/vdbe.c e6bf36b1df5ff32d222e8c96cacb2fb951be42a2
+F src/vdbe.c f1a8e5bf7747f2e731812804cb65d4d07d86862e
 F src/vdbe.h c044be7050ac6bf596eecc6ab159f5dbc020a3b7
-F src/vdbeInt.h d8a56a491b752dbb5f671963b8c861ec72ea875e
+F src/vdbeInt.h 29b25318a0286c4b2599c0fbef6acf524398489a
 F src/vdbeapi.c 97129bec6b1553da50d8e73f523c278bda66d9f6
 F src/vdbeaux.c 52d9b840859f260ce8418be9333dd77c902e1c74
 F src/vdbeblob.c 3e82a797b60c3b9fed7b8de8c539ca7607874937
@@ -1530,7 +1530,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 42db7cd2c0b367f7dfe733bdaf006538937b812a
-R 725472132a567caa1a975d92e1d85b3c
+P 51d0aed8d63d0710e4aa8925ff18cf3c45dc9e42
+R eacb8afe762fb37c4ccfd0b85c6e6ad7
 U drh
-Z 171f352f5da597b47d092f93a00f48a7
+Z e647112eb568bcacd99f7ceac7bd6ee3

manifest.uuid

@@ -1 +1 @@
-51d0aed8d63d0710e4aa8925ff18cf3c45dc9e42
+345b46be75bdf6f9fb7367a6164d89bae11995a6

src/btree.c

@@ -7941,16 +7941,18 @@ static int balance(BtCursor *pCur){
 **
 ** If the seekResult parameter is non-zero, then a successful call to
 ** MovetoUnpacked() to seek cursor pCur to (pKey,nKey) has already
-** been performed. seekResult is the search result returned (a negative
-** number if pCur points at an entry that is smaller than (pKey, nKey), or
-** a positive value if pCur points at an entry that is larger than 
-** (pKey, nKey)). 
+** been performed.  In other words, if seekResult!=0 then the cursor
+** is currently pointing to a cell that will be adjacent to the cell
+** to be inserted.  If seekResult<0 then pCur points to a cell that is
+** smaller then (pKey,nKey).  If seekResult>0 then pCur points to a cell
+** that is larger than (pKey,nKey).
 **
-** If the seekResult parameter is non-zero, then the caller guarantees that
-** cursor pCur is pointing at the existing copy of a row that is to be
-** overwritten.  If the seekResult parameter is 0, then cursor pCur may
-** point to any entry or to no entry at all and so this function has to seek
-** the cursor before the new key can be inserted.
+** If seekResult==0, that means pCur is pointing at some unknown location.
+** In that case, this routine must seek the cursor to the correct insertion
+** point for (pKey,nKey) before doing the insertion.  For index btrees,
+** if pX->nMem is non-zero, then pX->aMem contains pointers to the unpacked
+** key values and pX->aMem can be used instead of pX->pKey to avoid having
+** to decode the key.
 */
 int sqlite3BtreeInsert(
   BtCursor *pCur,                /* Insert data into the table of this cursor */

src/vdbe.c

@@ -4322,15 +4322,10 @@ case OP_NewRowid: {           /* out2 */
 ** then rowid is stored for subsequent return by the
 ** sqlite3_last_insert_rowid() function (otherwise it is unmodified).
 **
-** If the OPFLAG_USESEEKRESULT flag of P5 is set and if the result of
-** the last seek operation (OP_NotExists or OP_SeekRowid) was a success,
-** then this
-** operation will not attempt to find the appropriate row before doing
-** the insert but will instead overwrite the row that the cursor is
-** currently pointing to.  Presumably, the prior OP_NotExists or
-** OP_SeekRowid opcode
-** has already positioned the cursor correctly.  This is an optimization
-** that boosts performance by avoiding redundant seeks.
+** If the OPFLAG_USESEEKRESULT flag of P5 is set, the implementation might
+** run faster by avoiding an unnecessary seek on cursor P1.  However,
+** the OPFLAG_USESEEKRESULT flag must only be set if there have been no prior
+** seeks on the cursor or if the most recent seek used a key equal to P3.
 **
 ** If the OPFLAG_ISUPDATE flag is set, then this opcode is part of an
 ** UPDATE operation.  Otherwise (if the flag is clear) then this opcode
@@ -5036,9 +5031,11 @@ next_tail:
 ** incremented by this instruction.  If the OPFLAG_NCHANGE bit is clear,
 ** then the change counter is unchanged.
 **
-** If P5 has the OPFLAG_USESEEKRESULT bit set, then the cursor must have
-** just done a seek to the spot where the new entry is to be inserted.
-** This flag avoids doing an extra seek.
+** If the OPFLAG_USESEEKRESULT flag of P5 is set, the implementation might
+** run faster by avoiding an unnecessary seek on cursor P1.  However,
+** the OPFLAG_USESEEKRESULT flag must only be set if there have been no prior
+** seeks on the cursor or if the most recent seek used a key equivalent
+** to P2. 
 **
 ** This instruction only works for indices.  The equivalent instruction
 ** for tables is OP_Insert.

src/vdbeInt.h

@@ -96,7 +96,10 @@ struct VdbeCursor {
   } uc;
   Btree *pBt;           /* Separate file holding temporary table */
   KeyInfo *pKeyInfo;    /* Info about index keys needed by index cursors */
-  int seekResult;       /* Result of previous sqlite3BtreeMoveto() */
+  int seekResult;       /* Result of previous sqlite3BtreeMoveto() or 0
+                        ** if there have been no prior seeks on the cursor. */
+  /* NB: seekResult does not distinguish between "no seeks have ever occurred
+  ** on this cursor" and "the most recent seek was an exact match". */
   i64 seqCount;         /* Sequence counter */
   i64 movetoTarget;     /* Argument to the deferred sqlite3BtreeMoveto() */
   VdbeCursor *pAltCursor; /* Associated index cursor from which to read */