Convert the hint expression of the CursorHint opcode into a string for

display by EXPLAIN.

FossilOrigin-Name: 12640cb22240ee436cad99360ceb9a208edd14f5

main.mk

@@ -242,6 +242,7 @@ TESTSRC = \
   $(TOP)/src/test_backup.c \
   $(TOP)/src/test_btree.c \
   $(TOP)/src/test_config.c \
+  $(TOP)/src/test_cursorhint.c \
   $(TOP)/src/test_demovfs.c \
   $(TOP)/src/test_devsym.c \
   $(TOP)/src/test_fs.c \

manifest

@@ -1,5 +1,5 @@
-C Increase\sthe\sversion\snumber\sto\s3.8.3.
-D 2013-12-07T17:01:23.631
+C Convert\sthe\shint\sexpression\sof\sthe\sCursorHint\sopcode\sinto\sa\sstring\sfor\ndisplay\sby\sEXPLAIN.
+D 2015-08-13T21:43:19.244
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in e1a9b4258bbde53f5636f4e238c65b7e11459e2b
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -142,7 +142,7 @@ F ext/rtree/viewrtree.tcl eea6224b3553599ae665b239bd827e182b466024
 F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895 x
 F ltmain.sh 3ff0879076df340d2e23ae905484d8c15d5fdea8
 F magic.txt f439556c5ce01ced70987e5ee86549a45165d9ff
-F main.mk 82fd90375561d7b66287ae5a8b09e1e027394019
+F main.mk a6fa2dee82ed65ef48edc82baa0b480366f53212
 F mkdll.sh 7d09b23c05d56532e9d44a50868eb4b12ff4f74a
 F mkextu.sh 416f9b7089d80e5590a29692c9d9280a10dbad9f
 F mkextw.sh d2a981497b404d6498f5ff3e3b1f3816bdfcb338
@@ -166,8 +166,8 @@ F src/auth.c 523da7fb4979469955d822ff9298352d6b31de34
 F src/backup.c 1809a7caa2504233bdddd12f5018422421789537
 F src/bitvec.c 19a4ba637bd85f8f63fc8c9bae5ade9fb05ec1cb
 F src/btmutex.c 976f45a12e37293e32cae0281b15a21d48a8aaa7
-F src/btree.c 4037f58ef3f4459d0b9bb1fc1aee1136277d9ba6
-F src/btree.h a61ddebc78c66795a2b93181321a116746302cc9
+F src/btree.c 9e6d189894f54744d1a20c63de5afb66342f0904
+F src/btree.h 450f1c6022ec89da529a57f3e704e87c6c14b34d
 F src/btreeInt.h f038e818bfadf75afbd09819ed93c26a333d39e0
 F src/build.c 9b40580b62916612678bdb69ce0286e39c29a862
 F src/callback.c f99a8957ba2adf369645fac0db09ad8adcf1caa2
@@ -175,7 +175,7 @@ F src/complete.c dc1d136c0feee03c2f7550bafc0d29075e36deac
 F src/ctime.c 77779efbe78dd678d84bfb4fc2e87b6b6ad8dccd
 F src/date.c 593c744b2623971e45affd0bde347631bdfa4625
 F src/delete.c b36db1f79ee50eaca979660c9dd36437f5410b93
-F src/expr.c 31a2b65339f6c3795d4cfa5e99798cd72f9fdfdf
+F src/expr.c cdfc50b604ea9c9bbaa44f1f0a5c6cc835e84a32
 F src/fault.c 160a0c015b6c2629d3899ed2daf63d75754a32bb
 F src/fkey.c 2ab0f5384b70594468ef3ac5c7ed8ca24bfd17d5
 F src/func.c ef30d26ae4d79bbc7300c74e77fd117a0ba30235
@@ -219,16 +219,16 @@ F src/printf.c da9119eb31a187a4b99f60aa4a225141c0ebb74b
 F src/random.c 0b2dbc37fdfbfa6bd455b091dfcef5bdb32dba68
 F src/resolve.c 7eda9097b29fcf3d2b42fdc17d1de672134e09b6
 F src/rowset.c 64655f1a627c9c212d9ab497899e7424a34222e0
-F src/select.c d41381d80a22d3a83352aeca274cccf264ac277a
+F src/select.c 44fa5a4a270ce70b59acb616b01bc897e6d1e7ac
 F src/shell.c 936a72ff784efff3832cce274a96ed0b036e6758
 F src/sqlite.h.in 125dc0b76f0116f1cd6f13536db52ba981e1c5bd
 F src/sqlite3.rc 11094cc6a157a028b301a9f06b3d03089ea37c3e
 F src/sqlite3ext.h 886f5a34de171002ad46fae8c36a7d8051c190fc
-F src/sqliteInt.h f3a5d663fe9c6c0b2ee7fc2e20a6204eaea5bc7c
+F src/sqliteInt.h ccf72d12670132233750c6275a8ed978a95839aa
 F src/sqliteLimit.h 164b0e6749d31e0daa1a4589a169d31c0dec7b3d
 F src/status.c 7ac05a5c7017d0b9f0b4bcd701228b784f987158
 F src/table.c 2cd62736f845d82200acfa1287e33feb3c15d62e
-F src/tclsqlite.c 651b10698c87bbc3ae5772e2491e3444c5bbf153
+F src/tclsqlite.c 571af8d366a8c00106c8c4bfa5b2ab07a9e58baf
 F src/test1.c 760e0419705f712d80595f47199568cd7e3b57a4
 F src/test2.c 7355101c085304b90024f2261e056cdff13c6c35
 F src/test3.c 1c0e5d6f080b8e33c1ce8b3078e7013fdbcd560c
@@ -243,6 +243,7 @@ F src/test_autoext.c dea8a01a7153b9adc97bd26161e4226329546e12
 F src/test_backup.c 3875e899222b651e18b662f86e0e50daa946344e
 F src/test_btree.c 5b89601dcb42a33ba8b820a6b763cc9cb48bac16
 F src/test_config.c 10d0e00dd6315879a6d9fac20bd063c7bbbfb8f8
+F src/test_cursorhint.c 7c37315e15d6543689e8b48979a8eb370baa3cfc
 F src/test_demovfs.c 69b2085076654ebc18014cbc6386f04409c959a9
 F src/test_devsym.c e7498904e72ba7491d142d5c83b476c4e76993bc
 F src/test_fs.c ced436e3d4b8e4681328409b8081051ce614e28f
@@ -280,11 +281,11 @@ F src/update.c d1c2477dcf14d90999d1935af4efb4806553250b
 F src/utf.c 6fc6c88d50448c469c5c196acf21617a24f90269
 F src/util.c 76ed0519296e3f62e97e57dab1999e34184c8e49
 F src/vacuum.c 3728d74919d4fb1356f9e9a13e27773db60b7179
-F src/vdbe.c 54894fde8dc806d259e015ac7c9680145e725835
-F src/vdbe.h c06f0813f853566457ce9cfb1a4a4bc39a5da644
-F src/vdbeInt.h 05fbda0e061dbc4aaa2709a8cccf3515c245b263
+F src/vdbe.c 54e269c6268a6f37697e27d6bc572674f14b1581
+F src/vdbe.h 57b87844270b2e92647b8b82a8948f7a29efae8d
+F src/vdbeInt.h 9ad955ca89d4dc4b6056cece1896b4b85a8521fe
 F src/vdbeapi.c 93a22a9ba2abe292d5c2cf304d7eb2e894dde0ed
-F src/vdbeaux.c 09b79d475f5af2b3b5068f639609d88e0ced9d95
+F src/vdbeaux.c f4ed66c45336e42e7f1bdaccf7586c84eba06bac
 F src/vdbeblob.c 8cd05a5630e6d5563ad017bf82edaf812b28acde
 F src/vdbemem.c 20e349d2ca928802fc8f2d42a2cc488fd6981d3f
 F src/vdbesort.c 9d83601f9d6243fe70dd0169a2820c5ddfd48147
@@ -293,7 +294,7 @@ F src/vtab.c 21b932841e51ebd7d075e2d0ad1415dce8d2d5fd
 F src/wal.c 7dc3966ef98b74422267e7e6e46e07ff6c6eb1b4
 F src/wal.h df01efe09c5cb8c8e391ff1715cca294f89668a4
 F src/walker.c e9e593d5bb798c3e67fc3893dfe7055c9e7d8d74
-F src/where.c e6a4e713abe6f995495ea53dd6a5e48f88b53883
+F src/where.c 907fd82f4f8fc89d8a72d44caf5a5679c0769630
 F src/whereInt.h 96a75c61f1d2b9d4a8e4bb17d89deb0cf7cba358
 F test/8_3_names.test ebbb5cd36741350040fd28b432ceadf495be25b2
 F test/aggerror.test a867e273ef9e3d7919f03ef4f0e8c0d2767944f2
@@ -420,6 +421,7 @@ F test/crashtest1.c 09c1c7d728ccf4feb9e481671e29dda5669bbcc2
 F test/createtab.test b5de160630b209c4b8925bdcbbaf48cc90b67fe8
 F test/cse.test 277350a26264495e86b1785f34d2d0c8600e021c
 F test/ctime.test 7bd009071e242aac4f18521581536b652b789a47
+F test/cursorhint.test e55ad8c466327ffb3511b60007102bca22314d0a
 F test/date.test 42973251b9429f2c41b77eb98a7b0b0ba2d3b2c0
 F test/dbstatus.test 8de104bb5606f19537d23cd553b41349b5ab1204
 F test/dbstatus2.test 10418e62b3db5dca070f0c3eef3ea13946f339c2
@@ -1146,7 +1148,11 @@ F tool/vdbe-compress.tcl f12c884766bd14277f4fcedcae07078011717381
 F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4
 F tool/warnings.sh d1a6de74685f360ab718efda6265994b99bbea01
 F tool/win/sqlite.vsix 030f3eeaf2cb811a3692ab9c14d021a75ce41fff
-P 369a23e00644f3ff8b6a2d2ed73b8cb65e9f124b
-R 0fdea442d6dfa8b801d4e6d289982778
+P 1efa6ed584172291edce78faf9021e577583d03b
+Q +206884718782331a7aaacc2c811e4e9d2effae91
+R fcae2238c266b3818e83c96b2fcbbede
+T *branch * cursor-hints-displayP4
+T *sym-cursor-hints-displayP4 *
+T -sym-cursor-hints *
 U drh
-Z 0e445b98f25b8020cec84ec084909f7b
+Z 41561b125b2ba8dcbfb094780611e534

manifest.uuid

@@ -1 +1 @@
-23d00f22872a907a8ebf5b80689ff7aa66686a07
+12640cb22240ee436cad99360ceb9a208edd14f5

src/btree.c

@@ -764,6 +764,21 @@ int sqlite3BtreeCursorHasMoved(BtCursor *pCur, int *pHasMoved){
   return SQLITE_OK;
 }
 
+#ifdef SQLITE_ENABLE_CURSOR_HINTS
+/*
+** Give a hint to the cursor that it only has to deliver rows for which
+** the expression pExpr is true.  Within this expression, rows of the
+** cursor are identified by Expr.op==TK_COLUMN with Expr.iTable==iTable.
+**
+** This interfaces is not used by the standard storage engine of SQLite.
+** It is only useful to application that replace SQLite's built-in storage
+** engine with their own.
+*/
+void sqlite3BtreeCursorHint(BtCursor *pCur, int iTable, const Expr *pExpr){
+  /* Alternative storage engines might use this. */
+}
+#endif /* SQLITE_ENABLE_CURSOR_HINTS */
+
 #ifndef SQLITE_OMIT_AUTOVACUUM
 /*
 ** Given a page number of a regular database page, return the page

src/btree.h

@@ -167,6 +167,9 @@ int sqlite3BtreeMovetoUnpacked(
   int *pRes
 );
 int sqlite3BtreeCursorHasMoved(BtCursor*, int*);
+#ifdef SQLITE_ENABLE_CURSOR_HINTS
+void sqlite3BtreeCursorHint(BtCursor*, int, const Expr*);
+#endif
 int sqlite3BtreeDelete(BtCursor*);
 int sqlite3BtreeInsert(BtCursor*, const void *pKey, i64 nKey,
                                   const void *pData, int nData,

src/expr.c

@@ -1264,6 +1264,22 @@ int sqlite3ExprIsConstantOrFunction(Expr *p){
   return exprIsConst(p, 2);
 }
 
+#ifdef SQLITE_ENABLE_CURSOR_HINTS
+/*
+** Walk an expression tree.  Return 1 if the expression contains a
+** subquery of some kind.  Return 0 if there are no subqueries.
+*/
+int sqlite3ExprContainsSubquery(Expr *p){
+  Walker w;
+  memset(&w, 0, sizeof(w));
+  w.u.i = 1;
+  w.xExprCallback = sqlite3ExprWalkNoop;
+  w.xSelectCallback = selectNodeIsConstant;
+  sqlite3WalkExpr(&w, p);
+  return w.u.i==0;
+}
+#endif
+
 /*
 ** If the expression p codes a constant integer that is small enough
 ** to fit in a 32-bit integer, return 1 and put the value of the integer

src/select.c

@@ -3689,7 +3689,7 @@ static int selectExpander(Walker *pWalker, Select *p){
 ** Walker.xSelectCallback is set to do something useful for every 
 ** subquery in the parser tree.
 */
-static int exprWalkNoop(Walker *NotUsed, Expr *NotUsed2){
+int sqlite3ExprWalkNoop(Walker *NotUsed, Expr *NotUsed2){
   UNUSED_PARAMETER2(NotUsed, NotUsed2);
   return WRC_Continue;
 }
@@ -3710,7 +3710,7 @@ static int exprWalkNoop(Walker *NotUsed, Expr *NotUsed2){
 static void sqlite3SelectExpand(Parse *pParse, Select *pSelect){
   Walker w;
   memset(&w, 0, sizeof(w));
-  w.xExprCallback = exprWalkNoop;
+  w.xExprCallback = sqlite3ExprWalkNoop;
   w.pParse = pParse;
   if( pParse->hasCompound ){
     w.xSelectCallback = convertCompoundSelectToSubquery;
@@ -3774,7 +3774,7 @@ static void sqlite3SelectAddTypeInfo(Parse *pParse, Select *pSelect){
   Walker w;
   memset(&w, 0, sizeof(w));
   w.xSelectCallback = selectAddSubqueryTypeInfo;
-  w.xExprCallback = exprWalkNoop;
+  w.xExprCallback = sqlite3ExprWalkNoop;
   w.pParse = pParse;
   w.bSelectDepthFirst = 1;
   sqlite3WalkSelect(&w, pSelect);

src/sqliteInt.h

@@ -1064,6 +1064,7 @@ struct sqlite3 {
 #define SQLITE_OmitNoopJoin   0x0400   /* Omit unused tables in joins */
 #define SQLITE_Stat3          0x0800   /* Use the SQLITE_STAT3 table */
 #define SQLITE_AdjustOutEst   0x1000   /* Adjust output estimates using WHERE */
+#define SQLITE_CursorHints    0x2000   /* Add OP_CursorHint opcodes */
 #define SQLITE_AllOpts        0xffff   /* All optimizations */
 
 /*
@@ -2616,6 +2617,7 @@ int sqlite3WalkExprList(Walker*, ExprList*);
 int sqlite3WalkSelect(Walker*, Select*);
 int sqlite3WalkSelectExpr(Walker*, Select*);
 int sqlite3WalkSelectFrom(Walker*, Select*);
+int sqlite3ExprWalkNoop(Walker*, Expr*);
 
 /*
 ** Return code from the parse-tree walking primitives and their
@@ -2970,6 +2972,7 @@ void sqlite3LeaveMutexAndCloseZombie(sqlite3*);
 int sqlite3ExprIsConstant(Expr*);
 int sqlite3ExprIsConstantNotJoin(Expr*);
 int sqlite3ExprIsConstantOrFunction(Expr*);
+int sqlite3ExprContainsSubquery(Expr*);
 int sqlite3ExprIsInteger(Expr*, int*);
 int sqlite3ExprCanBeNull(const Expr*);
 void sqlite3ExprCodeIsNullJump(Vdbe*, const Expr*, int, int);

src/tclsqlite.c

@@ -3672,6 +3672,7 @@ static void init_all(Tcl_Interp *interp){
     extern int Sqlitetest9_Init(Tcl_Interp*);
     extern int Sqlitetestasync_Init(Tcl_Interp*);
     extern int Sqlitetest_autoext_Init(Tcl_Interp*);
+    extern int Sqlitetest_cursorhint_Init(Tcl_Interp*);
     extern int Sqlitetest_demovfs_Init(Tcl_Interp *);
     extern int Sqlitetest_func_Init(Tcl_Interp*);
     extern int Sqlitetest_hexio_Init(Tcl_Interp*);
@@ -3715,6 +3716,7 @@ static void init_all(Tcl_Interp *interp){
     Sqlitetest9_Init(interp);
     Sqlitetestasync_Init(interp);
     Sqlitetest_autoext_Init(interp);
+    Sqlitetest_cursorhint_Init(interp);
     Sqlitetest_demovfs_Init(interp);
     Sqlitetest_func_Init(interp);
     Sqlitetest_hexio_Init(interp);

src/test_cursorhint.c

@@ -0,0 +1,162 @@
+/*
+** 2008 March 19
+**
+** The author disclaims copyright to this source code.  In place of
+** a legal notice, here is a blessing:
+**
+**    May you do good and not evil.
+**    May you find forgiveness for yourself and forgive others.
+**    May you share freely, never taking more than you give.
+**
+*************************************************************************
+** Code for testing all sorts of SQLite interfaces.  This code
+** implements new SQL functions used by the test scripts.
+*/
+#include "sqlite3.h"
+#include "tcl.h"
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+
+#include "sqliteInt.h"
+#include "vdbeInt.h"
+
+struct CursorHintGlobal {
+  Tcl_Interp *interp;
+  Tcl_Obj *pScript;
+} cursorhintglobal;
+
+static char *exprToString(Mem *aMem, Expr *pExpr){
+  char *zRet = 0;
+  char *zBinOp = 0;
+
+  switch( pExpr->op ){
+    case TK_STRING:
+      zRet = sqlite3_mprintf("%Q", pExpr->u.zToken);
+      break;
+
+    case TK_INTEGER:
+      zRet = sqlite3_mprintf("%d", pExpr->u.iValue);
+      break;
+
+    case TK_NULL:
+      zRet = sqlite3_mprintf("%s", "NULL");
+      break;
+
+    case TK_REGISTER: {
+      Mem *pMem = &aMem[pExpr->iTable];
+      if( pMem->flags & MEM_Int ){
+        zRet = sqlite3_mprintf("%lld", pMem->u.i);
+      }
+      else if( pMem->flags & MEM_Real ){
+        zRet = sqlite3_mprintf("%f", pMem->r);
+      }
+      else if( pMem->flags & MEM_Str ){
+        zRet = sqlite3_mprintf("%.*Q", pMem->n, pMem->z);
+      }
+      else if( pMem->flags & MEM_Blob ){
+      }
+      else{
+        zRet = sqlite3_mprintf("%s", "NULL");
+      }
+      break;
+    }
+
+    case TK_COLUMN: {
+      zRet = sqlite3_mprintf("col(%d)", (int)pExpr->iColumn);
+      break;
+    }
+
+    case TK_LT:      zBinOp = "<";      break;
+    case TK_LE:      zBinOp = "<=";     break;
+    case TK_GT:      zBinOp = ">";      break;
+    case TK_GE:      zBinOp = ">=";     break;
+    case TK_NE:      zBinOp = "!=";     break;
+    case TK_EQ:      zBinOp = "==";     break;
+    case TK_IS:      zBinOp = "IS";     break;
+    case TK_ISNOT:   zBinOp = "IS NOT"; break;
+    case TK_AND:     zBinOp = "AND";    break;
+    case TK_OR:      zBinOp = "OR";     break;
+    case TK_PLUS:    zBinOp = "+";      break;
+    case TK_STAR:    zBinOp = "*";      break;
+    case TK_MINUS:   zBinOp = "-";      break;
+    case TK_REM:     zBinOp = "%";      break;
+    case TK_BITAND:  zBinOp = "&";      break;
+    case TK_BITOR:   zBinOp = "|";      break;
+    case TK_SLASH:   zBinOp = "/";      break;
+    case TK_LSHIFT:  zBinOp = "<<";     break;
+    case TK_RSHIFT:  zBinOp = ">>";     break;
+    case TK_CONCAT:  zBinOp = "||";     break;
+
+    default:
+      zRet = sqlite3_mprintf("%s", "expr");
+      break;
+  }
+
+  if( zBinOp ){
+    zRet = sqlite3_mprintf("(%z %s %z)", 
+        exprToString(aMem, pExpr->pLeft),
+        zBinOp,
+        exprToString(aMem, pExpr->pRight)
+    );
+  }
+
+  return zRet;
+}
+
+void sqlite3BtreeCursorHintTest(Mem *aMem, Expr *pExpr){
+  if( cursorhintglobal.pScript ){
+    Tcl_Obj *pEval = Tcl_DuplicateObj(cursorhintglobal.pScript);
+    char *zExpr;
+    Tcl_Obj *pObj;
+    Tcl_IncrRefCount(pEval);
+    zExpr = exprToString(aMem, pExpr);
+    pObj = Tcl_NewStringObj(zExpr, -1);
+    sqlite3_free(zExpr);
+    Tcl_ListObjAppendElement(cursorhintglobal.interp, pEval, pObj);
+    Tcl_EvalObjEx(cursorhintglobal.interp, pEval, TCL_GLOBAL_ONLY);
+    Tcl_DecrRefCount(pEval);
+  }
+}
+
+/*
+** Usage: cursorhint_hook SCRIPT
+*/
+static int install_cursorhint_hook(
+  ClientData clientData, /* Pointer to sqlite3_enable_XXX function */
+  Tcl_Interp *interp,    /* The TCL interpreter that invoked this command */
+  int objc,              /* Number of arguments */
+  Tcl_Obj *CONST objv[]  /* Command arguments */
+){
+  if( objc!=1 && objc!=2 ){
+    Tcl_WrongNumArgs(interp, 1, objv, "?SCRIPT?");
+    return TCL_ERROR;
+  }
+  if( cursorhintglobal.pScript ){
+    Tcl_DecrRefCount(cursorhintglobal.pScript);
+    memset(&cursorhintglobal, 0, sizeof(cursorhintglobal));
+  }
+  if( objc==2 ){
+    cursorhintglobal.interp = interp;
+    cursorhintglobal.pScript = Tcl_DuplicateObj(objv[1]);
+  }
+  return TCL_OK;
+}
+
+/*
+** Register commands with the TCL interpreter.
+*/
+int Sqlitetest_cursorhint_Init(Tcl_Interp *interp){
+  static struct {
+     char *zName;
+     Tcl_ObjCmdProc *xProc;
+  } aObjCmd[] = {
+     { "cursorhint_hook",    install_cursorhint_hook },
+  };
+  int i;
+  for(i=0; i<sizeof(aObjCmd)/sizeof(aObjCmd[0]); i++){
+    Tcl_CreateObjCommand(interp, aObjCmd[i].zName, aObjCmd[i].xProc, 0, 0);
+  }
+  sqlite3_initialize();
+  return TCL_OK;
+}

src/vdbe.c

@@ -6170,6 +6170,30 @@ case OP_Trace: {
 }
 #endif
 
+#ifdef SQLITE_ENABLE_CURSOR_HINTS
+/* Opcode: CursorHint P1 P2 * P4 *
+**
+** Provide a hint to cursor P1 that it only needs to return rows that
+** satisfy the Expr tree given in P4.  P2 is the table number of cursor P1
+** such that references to cursor P1 in the Expr tree are given by
+** Expr.iTable==P2.
+*/
+case OP_CursorHint: {
+  VdbeCursor *pC;
+
+  assert( pOp->p1>=0 && pOp->p1<p->nCursor );
+  assert( pOp->p4type==P4_EXPR );
+  pC = p->apCsr[pOp->p1];
+  if( pC ){
+    sqlite3BtreeCursorHint(pC->pCursor, pOp->p2, pOp->p4.pExpr);
+#ifdef SQLITE_TEST
+    void sqlite3BtreeCursorHintTest(Mem*, Expr*);
+    sqlite3BtreeCursorHintTest(p->aMem, pOp->p4.pExpr);
+#endif
+  }
+  break;
+}
+#endif /* SQLITE_ENABLE_CURSOR_HINTS */
 
 /* Opcode: Noop * * * * *
 **

src/vdbe.h

@@ -59,6 +59,9 @@ struct VdbeOp {
     KeyInfo *pKeyInfo;     /* Used when p4type is P4_KEYINFO */
     int *ai;               /* Used when p4type is P4_INTARRAY */
     SubProgram *pProgram;  /* Used when p4type is P4_SUBPROGRAM */
+#ifdef SQLITE_ENABLE_CURSOR_HINTS
+    Expr *pExpr;           /* Used when p4type is P4_EXPR */
+#endif
     int (*xAdvance)(BtCursor *, int *);
   } p4;
 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
@@ -106,6 +109,7 @@ typedef struct VdbeOpList VdbeOpList;
 #define P4_COLLSEQ  (-4)  /* P4 is a pointer to a CollSeq structure */
 #define P4_FUNCDEF  (-5)  /* P4 is a pointer to a FuncDef structure */
 #define P4_KEYINFO  (-6)  /* P4 is a pointer to a KeyInfo structure */
+#define P4_EXPR     (-7)  /* P4 is a pointer to an Expr tree */
 #define P4_MEM      (-8)  /* P4 is a pointer to a Mem*    structure */
 #define P4_TRANSIENT  0   /* P4 is a pointer to a transient string */
 #define P4_VTAB     (-10) /* P4 is a pointer to an sqlite3_vtab structure */

src/vdbeInt.h

@@ -26,6 +26,17 @@
 # define SQLITE_MAX_SCHEMA_RETRY 50
 #endif
 
+/*
+** VDBE_DISPLAY_P4 is true or false depending on whether or not the
+** "explain" P4 display logic is enabled.
+*/
+#if !defined(SQLITE_OMIT_EXPLAIN) || !defined(NDEBUG) \
+     || defined(VDBE_PROFILE) || defined(SQLITE_DEBUG)
+# define VDBE_DISPLAY_P4 1
+#else
+# define VDBE_DISPLAY_P4 0
+#endif
+
 /*
 ** SQL is translated into a sequence of instructions to be
 ** executed by a virtual machine.  Each instruction is an instance

src/vdbeaux.c

@@ -639,6 +639,12 @@ static void freeP4(sqlite3 *db, int p4type, void *p4){
         if( db->pnBytesFreed==0 ) sqlite3KeyInfoUnref((KeyInfo*)p4);
         break;
       }
+#ifdef SQLITE_ENABLE_CURSOR_HINTS
+      case P4_EXPR: {
+        sqlite3ExprDelete(db, (Expr*)p4);
+        break;
+      }
+#endif
       case P4_MPRINTF: {
         if( db->pnBytesFreed==0 ) sqlite3_free(p4);
         break;
@@ -756,6 +762,15 @@ void sqlite3VdbeChangeP4(Vdbe *p, int addr, const char *zP4, int n){
   }else if( n==P4_KEYINFO ){
     pOp->p4.p = (void*)zP4;
     pOp->p4type = P4_KEYINFO;
+#ifdef SQLITE_ENABLE_CURSOR_HINTS
+  }else if( n==P4_EXPR ){
+    /* Responsibility for deleting the Expr tree is handed over to the
+    ** VDBE by this operation.  The caller should have already invoked
+    ** sqlite3ExprDup() or whatever other routine is needed to make a 
+    ** private copy of the tree. */
+    pOp->p4.pExpr = (Expr*)zP4;
+    pOp->p4type = P4_EXPR;
+#endif
   }else if( n==P4_VTAB ){
     pOp->p4.p = (void*)zP4;
     pOp->p4type = P4_VTAB;
@@ -932,9 +947,78 @@ static int displayComment(
 }
 #endif /* SQLITE_DEBUG */
 
+#if VDBE_DISPLAY_P4 && defined(SQLITE_ENABLE_CURSOR_HINTS)
+/*
+** Translate the P4.pExpr value for an OP_CursorHint opcode into text
+** that can be displayed in the P4 column of EXPLAIN output.
+*/
+static int displayP4Expr(int nTemp, char *zTemp, Expr *pExpr){
+  const char *zBinOp = 0;
+  switch( pExpr->op ){
+    case TK_STRING:
+      sqlite3_snprintf(nTemp, zTemp, "%Q", pExpr->u.zToken);
+      break;
 
-#if !defined(SQLITE_OMIT_EXPLAIN) || !defined(NDEBUG) \
-     || defined(VDBE_PROFILE) || defined(SQLITE_DEBUG)
+    case TK_INTEGER:
+      sqlite3_snprintf(nTemp, zTemp, "%d", pExpr->u.iValue);
+      break;
+
+    case TK_NULL:
+      sqlite3_snprintf(nTemp, zTemp, "NULL");
+      break;
+
+    case TK_REGISTER: {
+      sqlite3_snprintf(nTemp, zTemp, "r[%d]", pExpr->iTable);
+      break;
+    }
+
+    case TK_COLUMN: {
+      sqlite3_snprintf(nTemp, zTemp, "c%d", (int)pExpr->iColumn);
+      break;
+    }
+
+    case TK_LT:      zBinOp = "<";        break;
+    case TK_LE:      zBinOp = "<=";       break;
+    case TK_GT:      zBinOp = ">";        break;
+    case TK_GE:      zBinOp = ">=";       break;
+    case TK_NE:      zBinOp = "!=";       break;
+    case TK_EQ:      zBinOp = "==";       break;
+    case TK_IS:      zBinOp = " IS ";     break;
+    case TK_ISNOT:   zBinOp = " IS NOT "; break;
+    case TK_AND:     zBinOp = " AND ";    break;
+    case TK_OR:      zBinOp = " OR ";     break;
+    case TK_PLUS:    zBinOp = "+";        break;
+    case TK_STAR:    zBinOp = "*";        break;
+    case TK_MINUS:   zBinOp = "-";        break;
+    case TK_REM:     zBinOp = "%";        break;
+    case TK_BITAND:  zBinOp = "&";        break;
+    case TK_BITOR:   zBinOp = "|";        break;
+    case TK_SLASH:   zBinOp = "/";        break;
+    case TK_LSHIFT:  zBinOp = "<<";       break;
+    case TK_RSHIFT:  zBinOp = ">>";       break;
+    case TK_CONCAT:  zBinOp = "||";       break;
+
+    default:
+      sqlite3_snprintf(nTemp, zTemp, "%s", "expr");
+      break;
+  }
+
+  if( zBinOp && nTemp>5 ){
+    int n = 1;
+    zTemp[0] = '(';
+    n += displayP4Expr(nTemp-n, zTemp+n, pExpr->pLeft);
+    sqlite3_snprintf(nTemp-n, zTemp+n, "%s", zBinOp);
+    n += sqlite3Strlen30(zTemp+n);
+    n += displayP4Expr(nTemp-n, zTemp+n, pExpr->pRight);
+    sqlite3_snprintf(nTemp-n, zTemp+n, ")");
+  }
+
+  return sqlite3Strlen30(zTemp);
+}
+#endif /* VDBE_DISPLAY_P4 && defined(SQLITE_ENABLE_CURSOR_HINTS) */
+
+
+#if VDBE_DISPLAY_P4
 /*
 ** Compute a string that describes the P4 parameter for an opcode.
 ** Use zTemp for any required temporary buffer space.
@@ -973,6 +1057,12 @@ static char *displayP4(Op *pOp, char *zTemp, int nTemp){
       assert( i<nTemp );
       break;
     }
+#ifdef SQLITE_ENABLE_CURSOR_HINTS
+    case P4_EXPR: {
+      displayP4Expr(nTemp, zTemp, pOp->p4.pExpr);
+      break;
+    }
+#endif
     case P4_COLLSEQ: {
       CollSeq *pColl = pOp->p4.pColl;
       sqlite3_snprintf(nTemp, zTemp, "(%.20s)", pColl->zName);
@@ -1041,7 +1131,7 @@ static char *displayP4(Op *pOp, char *zTemp, int nTemp){
   assert( zP4!=0 );
   return zP4;
 }
-#endif
+#endif /* VDBE_DISPLAY_P4 */
 
 /*
 ** Declare to the Vdbe that the BTree object at db->aDb[i] is used.

src/where.c

@@ -2715,6 +2715,90 @@ static void explainOneScan(
 # define explainOneScan(u,v,w,x,y,z)
 #endif /* SQLITE_OMIT_EXPLAIN */
 
+#ifdef SQLITE_ENABLE_CURSOR_HINTS
+
+/*
+** This function is called on every node of an expression tree used as an
+** argument to the OP_CursorHint instruction. If the node is a TK_COLUMN
+** that accesses any cursor other than (pWalker->u.i), do the following:
+**
+**   1) allocate a register and code an OP_Column instruction to read 
+**      the specified column into the new register, and
+**
+**   2) transform the expression node to a TK_REGISTER node that reads 
+**      from the newly populated register.
+*/
+static int codeCursorHintFixExpr(Walker *pWalker, Expr *pExpr){
+  int rc = WRC_Continue;
+  if( pExpr->op==TK_COLUMN && pExpr->iTable!=pWalker->u.i ){
+    Vdbe *v = pWalker->pParse->pVdbe;
+    int reg = ++pWalker->pParse->nMem;   /* Register for column value */
+    sqlite3ExprCodeGetColumnOfTable(
+        v, pExpr->pTab, pExpr->iTable, pExpr->iColumn, reg
+    );
+    pExpr->op = TK_REGISTER;
+    pExpr->iTable = reg;
+  }else if( pExpr->op==TK_AGG_FUNCTION ){
+    /* An aggregate function in the WHERE clause of a query means this must
+    ** be a correlated sub-query, and expression pExpr is an aggregate from
+    ** the parent context. Do not walk the function arguments in this case.
+    **
+    ** todo: It should be possible to replace this node with a TK_REGISTER
+    ** expression, as the result of the expression must be stored in a 
+    ** register at this point. The same holds for TK_AGG_COLUMN nodes. */
+    rc = WRC_Prune;
+  }
+  return rc;
+}
+
+/*
+** Insert an OP_CursorHint instruction if it is appropriate to do so.
+*/
+static void codeCursorHint(
+  WhereInfo *pWInfo,
+  int iLevel
+){
+  Parse *pParse = pWInfo->pParse;
+  sqlite3 *db = pParse->db;
+  Vdbe *v = pParse->pVdbe;
+  WhereLevel *pLevel;
+  Expr *pExpr = 0;
+  int iCur;
+  WhereClause *pWC;
+  WhereTerm *pTerm;
+  WhereLoop *pWLoop;
+  int i, j;
+
+  if( OptimizationDisabled(db, SQLITE_CursorHints) ) return;
+  pLevel = &pWInfo->a[iLevel];
+  pWLoop = pLevel->pWLoop;
+  iCur = pWInfo->pTabList->a[pLevel->iFrom].iCursor;
+  pWC = &pWInfo->sWC;
+  for(i=0; i<pWC->nTerm; i++){
+    pTerm = &pWC->a[i];
+    if( pTerm->wtFlags & (TERM_VIRTUAL|TERM_CODED) ) continue;
+    if( pTerm->prereqAll & pLevel->notReady ) continue;
+    if( ExprHasProperty(pTerm->pExpr, EP_FromJoin) ) continue;
+    if( sqlite3ExprContainsSubquery(pTerm->pExpr) ) continue;
+    for(j=0; j<pWLoop->nLTerm && pWLoop->aLTerm[j]!=pTerm; j++){}
+    if( j<pWLoop->nLTerm ) continue;
+    pExpr = sqlite3ExprAnd(db, pExpr, sqlite3ExprDup(db, pTerm->pExpr, 0));
+  }
+  if( pExpr!=0 ){
+    const char *a = (const char*)pExpr;
+    Walker sWalker;
+    memset(&sWalker, 0, sizeof(sWalker));
+    sWalker.xExprCallback = codeCursorHintFixExpr;
+    sWalker.pParse = pParse;
+    sWalker.u.i = pLevel->iTabCur;
+    sqlite3WalkExpr(&sWalker, pExpr);
+    sqlite3VdbeAddOp4(v, OP_CursorHint, pLevel->iTabCur, iCur, 0, a, P4_EXPR);
+  }
+}
+#else
+# define codeCursorHint(A,B)  /* No-op */
+#endif /* SQLITE_ENABLE_CURSOR_HINTS */
+
 
 /*
 ** Generate code for the start of the iLevel-th loop in the WHERE clause
@@ -2876,6 +2960,7 @@ static Bitmask codeOneLoopStart(
       pStart = pEnd;
       pEnd = pTerm;
     }
+    codeCursorHint(pWInfo, iLevel);
     if( pStart ){
       Expr *pX;             /* The expression that defines the start bound */
       int r1, rTemp;        /* Registers for holding the start boundary */
@@ -3061,6 +3146,7 @@ static Bitmask codeOneLoopStart(
     start_constraints = pRangeStart || nEq>0;
 
     /* Seek the index cursor to the start of the range. */
+    codeCursorHint(pWInfo, iLevel);
     nConstraint = nEq;
     if( pRangeStart ){
       Expr *pRight = pRangeStart->pExpr->pRight;
@@ -3408,6 +3494,7 @@ static Bitmask codeOneLoopStart(
     static const u8 aStep[] = { OP_Next, OP_Prev };
     static const u8 aStart[] = { OP_Rewind, OP_Last };
     assert( bRev==0 || bRev==1 );
+    codeCursorHint(pWInfo, iLevel);
     pLevel->op = aStep[bRev];
     pLevel->p1 = iCur;
     pLevel->p2 = 1 + sqlite3VdbeAddOp2(v, aStart[bRev], iCur, addrBrk);

test/cursorhint.test

@@ -0,0 +1,72 @@
+# 2014 July 15
+#
+# The author disclaims copyright to this source code.  In place of
+# a legal notice, here is a blessing:
+#
+#    May you do good and not evil.
+#    May you find forgiveness for yourself and forgive others.
+#    May you share freely, never taking more than you give.
+#
+#***********************************************************************
+# This file implements regression tests for SQLite library.
+#
+
+set testdir [file dirname $argv0]
+source $testdir/tester.tcl
+set testprefix cursorhint
+
+do_execsql_test 1.0 {
+  CREATE TABLE t1(a,b);
+  CREATE TABLE t2(x,y);
+  INSERT INTO t1 VALUES(10, 15);
+  INSERT INTO t1 VALUES(20, 25);
+  INSERT INTO t2 VALUES('ten', 'fifteen');
+  INSERT INTO t2 VALUES('twenty', 'twentyfive');
+  PRAGMA automatic_index = 0;
+}
+
+proc H {expr} {
+  lappend ::cursorhint $expr
+}
+
+proc do_cursorhint_test {tn sql hints} {
+  cursorhint_hook H
+  set ::cursorhint [list]
+  set testbody [subst {
+    execsql {$sql}
+    set ::cursorhint
+  }]
+  uplevel [list do_test $tn $testbody [list {*}$hints]]
+  cursorhint_hook
+}
+
+
+do_cursorhint_test 1.1 {
+  SELECT * FROM t1 CROSS JOIN t2 WHERE a=x;
+} {
+  {(10 == col(0))} 
+  {(20 == col(0))}
+}
+
+do_cursorhint_test 1.2 {
+  SELECT * FROM t2 CROSS JOIN t1 WHERE a=x;
+} {
+  {(col(0) == 'ten')} 
+  {(col(0) == 'twenty')}
+}
+
+do_cursorhint_test 1.3 {
+  SELECT * FROM t1 CROSS JOIN t2 WHERE b=15;
+} {
+  {(col(1) == 15)} 
+}
+
+do_cursorhint_test 1.3 {
+  SELECT * FROM t1 CROSS JOIN t2 WHERE y=b+1;
+} {
+  {(col(1) == (15 + 1))} 
+  {(col(1) == (25 + 1))} 
+}
+
+
+finish_test