Improved comments on the new OP_SeekScan opcode.

FossilOrigin-Name: 6110fdd5bb7b4ae5c065404c802ae726362ef084966b73cffe58c4bfb98689d2

diff --git a/manifest b/manifest
index c6fe2f1e83c28cd269aa25934a013c2d13c8162f..9da918b734973bf3490337e4e08a8ef20fd5d989 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Improved\sperformance\sby\smanually\sin-lining\sthe\ssqlite3VdbeIdxKeyCompare()\nroutine\sfor\sthe\sOP_IdxGT\sopcode\sand\sits\skin.
-D 2020-09-29T16:05:09.270
+C Improved\scomments\son\sthe\snew\sOP_SeekScan\sopcode.
+D 2020-09-29T17:29:11.276
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -607,7 +607,7 @@ F src/upsert.c 2920de71b20f04fe25eb00b655d086f0ba60ea133c59d7fa3325c49838818e78
 F src/utf.c ee39565f0843775cc2c81135751ddd93eceb91a673ea2c57f61c76f288b041a0
 F src/util.c c0c7977de7ef9b8cb10f6c85f2d0557889a658f817b0455909a49179ba4c8002
 F src/vacuum.c 492422c1463c076473bae1858799c7a0a5fe87a133d1223239447c422cd26286
-F src/vdbe.c 72fa5727e874b51f24b72ef12dfec8738e724b4c70c308f1e9fc3b955375f214
+F src/vdbe.c f1dfd1fc1911876ac8ade2d1e9c3055242ec9de857fc7f72c9c75f712e6acde3
 F src/vdbe.h 83603854bfa5851af601fc0947671eb260f4363e62e960e8a994fb9bbcd2aaa1
 F src/vdbeInt.h 3ca5e9fd6e095a8b6cf6bc3587a46fc93499503b2fe48951e1034ba9e2ce2f6e
 F src/vdbeapi.c c5e7cb2ab89a24d7f723e87b508f21bfb1359a04db5277d8a99fd1e015c12eb9
@@ -1880,7 +1880,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 8fd7d8dfcd515aa6b65d6eb27b033d3b3a31db467b9100cc13c62bc60113019e
-R 4899ba483a1f0c89bb1918b365591512
+P 2206a2c848a122ee220c89427f9be0460cba0706f58852139d7b37184ce29a29
+R 1f20d571e0b39b4a04d29411b17457a4
 U drh
-Z ee02d60aca1d7fbfb9e679e7d8012083
+Z fc780e21a0f22dec17fca15dd256ba17

diff --git a/manifest.uuid b/manifest.uuid
index c1f427098e2768eed44c9d1fd9754da73d9415b2..f5cbb057c302ccfd4727e4a19efea3ce4a432749 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-2206a2c848a122ee220c89427f9be0460cba0706f58852139d7b37184ce29a29
\ No newline at end of file
+6110fdd5bb7b4ae5c065404c802ae726362ef084966b73cffe58c4bfb98689d2
\ No newline at end of file

diff --git a/src/vdbe.c b/src/vdbe.c
index 2f38a0b3a5e45edb0cf92986160c47fab699396d..dacda150746dba276c6ecc9f3816632aa23323b9 100644 (file)
--- a/src/vdbe.c
+++ b/src/vdbe.c
@@ -4384,45 +4384,53 @@ seek_not_found:
 }
 
 
-/* Opcode: SeekScan
+/* Opcode: SeekScan  P1 * * * *
 ** Synopsis: Scan-ahead up to P1 rows
 **
-** This opcode is a prefix.  It must be followed immediately by
-** OP_SeekGE and then OP_IdxGT.  This opcode should occur in no other
-** context.  That constraint is verified using assert() statements in
-** the code.
+** This opcode is a prefix opcode to OP_SeekGE.  In other words, this
+** opcode must be immediately followed by OP_SeekGE.  Furthermore, the
+** OP_SeekGE must be followed by OP_IdxGT.  These constraints are
+** checked by assert() statements.
+**
+** This opcode uses the P1 through P4 operands of the subsequent
+** OP_SeekGE.  In the text that follows, the operands of the subsequent
+** OP_SeekGE opcode are denoted as SeekOP.P1 through SeekOP.P4.   Only
+** the P1 operand of this opcode is used, and it is denoted as This.P1.
 **
 ** This opcode helps to optimize IN operators on a multi-column index
-** where the IN operator is on the later terms of the index.
+** where the IN operator is on the later terms of the index by avoiding
+** unnecessary seeks on the btree, substituting steps to the next row
+** of the b-tree instead.  A correct answer is obtained if this opcode
+** is omitted or is a no-op.
 **
-** The P3 and P4 operations of the OP_SeekGE opcode that follows this
-** opcode identify an unpacked key which is the desired entry that
-** we want to advance the cursor to.  Call this the "target".
+** The SeekGE.P3 and SeekGE.P4 operands identify an unpacked key which
+** is the desired entry that we want the cursor SeekGE.P1 to be pointing
+** to.  Call this SeekGE.P4/P5 row the "target".
 **
 ** If the OP_SeekGE opcode that immediately follows this opcode has
-** never run before, then this opcode is a no-op and control passes
+** never run before, which is to say if the SeekGE.P1 cursor is not pointing
+** to a valid raow, then this opcode is a no-op and control passes
 ** through into the OP_SeekGE.
 **
-** If the subsequent OP_SeekGE opcode has run before, then that prior
-** might OP_SeekGE might have left the cursor pointing any entry that
-** is close to the target.  This routine checks, and if possible
-** bypasses the OP_SeekGE.
-**
-** If the cursor is past the target, jump immediately to the
-** P2 of the subsequent OP_SeekGE.
-**
-** If the cursor is less than the target, then step forward up to P1
-** times trying to find a match.  If during these steps, the
-** cursor moves past the target, then jump immediately to
-** the P2 of the subsequent OP_SeekGE.  If a match is found, jump
-** to the first instruction past the OP_IdxGT that follows the
-** OP_SeekGE.  (In other words, skip over the next two opcodes).
-** If P1 steps are performed and the cursor is still less than the
-** target, then fall through into OP_SeekGE opcode.
-**
-** This opcode is an optimization.  This opcode can be a no-op and
-** the correct answer should still be obtained.  The purpose of this
-** opcode is to bypass unnecessary OP_SeekGE operations.
+** If the SeekGE.P1 cursor is pointing to a valid row, then that row
+** might be the target row, or it might be near and slightly before the
+** target row.  This opcode attempts to position the cursor on the target
+** row by, perhaps stepping by invoking sqlite3BtreeStep() on the cursor
+** between 0 and This.P1 times.
+**
+** There are three possible outcomes from this opcode:<ol>
+**
+** <li> If after This.P1 steps, the cursor is still point to a place that
+**      is earlier in the btree than the target row,
+**      then fall through into the subsquence OP_SeekGE opcode.
+**
+** <li> If the cursor is successfully moved to the target row by 0 or more
+**      sqlite3BtreeNext() calls, then jump to the first instruction after the
+**      OP_IdxGT opcode - or in other words, skip the next two opcodes.
+**
+** <li> If the cursor ends up past the target row (indicating the the target
+**      row does not exist in the btree) then jump to SeekOP.P2. 
+** </ol>
 */
 case OP_SeekScan: {
   VdbeCursor *pC;