Add further comments to window.c.

FossilOrigin-Name: 900464567b2a5ce0c278a3297e4be1968f609258608aa0fbe2fc67709aa22a4b

manifest

@@ -1,5 +1,5 @@
-C New\stest\scases\sfor\swindow\sfunctions\swith\sRANGE\sBETWEEN\sand\sDESC\sNULLS\sFIRST.
+C Add\sfurther\scomments\sto\swindow.c.
-D 2019-08-30T16:46:12.848
+D 2019-08-30T17:28:55.760
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -613,7 +613,7 @@ F src/where.c fb546afbdbedc77a6193a236db92f6f85bc8e17412ec596230dd8aee03a93716
 F src/whereInt.h 4a296fd4fa79fdcbc2b5e8c1b898901617655811223e1082b899c23ecb092217
 F src/wherecode.c 535c8e228478fd971b9a5b6cb6773995b0fbf7020d5989508a5094ce5b8cd95b
 F src/whereexpr.c 2757afbd5cfdbb420f9d0392e1bd5f5c0e33dee50a8c692befc7e502308e449f
-F src/window.c 701bea99097fd9f2c49e0af54446c986853e639fa297248ea62fac5e3f3b8dba
+F src/window.c ff37ca403ad3c47bb1e60b0e88c546aa5194524dc20d7f75e866187a093ae5d7
 F test/8_3_names.test ebbb5cd36741350040fd28b432ceadf495be25b2
 F test/affinity2.test b03930d288e38b07f55023a58538ad174605695e98934bdab1facf6bd9ecc436
 F test/affinity3.test 6a101af2fc945ce2912f6fe54dd646018551710d
@@ -1838,7 +1838,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 39b4cad4a51bb5116d62ffb16ac36d96a9280321b049eb2d008605392f52a459
+P f7002f86c780e279c9f8a6268f317586519c059c9de2115ff6f1cad272570c29
-R 5b7566c6e8c614d220a50ba45c732f15
+R 717428315655334cbf16abae9c8648f7
-U drh
+U dan
-Z 7f59914616f53a7b55c42685c9ae4ee5
+Z e01e05b9266977bc594b107aacdc1011

manifest.uuid

@@ -1 +1 @@
-f7002f86c780e279c9f8a6268f317586519c059c9de2115ff6f1cad272570c29
+900464567b2a5ce0c278a3297e4be1968f609258608aa0fbe2fc67709aa22a4b

src/window.c

@@ -1499,19 +1499,78 @@ static void windowAggStep(
 
 typedef struct WindowCodeArg WindowCodeArg;
 typedef struct WindowCsrAndReg WindowCsrAndReg;
+
+/*
+** See comments above struct WindowCodeArg.
+*/
 struct WindowCsrAndReg {
-  int csr;
+  int csr;                        /* Cursor number */
-  int reg;
+  int reg;                        /* First in array of peer values */
 };
 
+/*
+** A single instance of this structure is allocated on the stack by 
+** sqlite3WindowCodeStep() and a pointer to it passed to the various helper
+** routines. This is to reduce the number of arguments required by each
+** helper function.
+**
+** regArg:
+**   Each window function requires an accumulator register (just as an
+**   ordinary aggregate function does). This variable is set to the first
+**   in an array of accumulator registers - one for each window function
+**   in the WindowCodeArg.pMWin list.
+**
+** eDelete:
+**   The window functions implementation sometimes caches the input rows
+**   that it processes in a temporary table. If it is not zero, this
+**   variable indicates when rows may be removed from the temp table (in
+**   order to reduce memory requirements - it would always be safe just
+**   to leave them there). Possible values for eDelete are:
+**
+**      WINDOW_RETURN_ROW:
+**        An input row can be discarded after it is returned to the caller.
+**
+**      WINDOW_AGGINVERSE:
+**        An input row can be discarded after the window functions xInverse()
+**        callbacks have been invoked in it.
+**
+**      WINDOW_AGGSTEP:
+**        An input row can be discarded after the window functions xStep()
+**        callbacks have been invoked in it.
+**
+** start,current,end
+**   Consider a window-frame similar to the following:
+**
+**     (ORDER BY a, b GROUPS BETWEEN 2 PRECEDING AND 2 FOLLOWING)
+**
+**   The windows functions implmentation caches the input rows in a temp
+**   table, sorted by "a, b" (it actually populates the cache lazily, and
+**   aggressively removes rows once they are no longer required, but that's
+**   a mere detail). It keeps three cursors open on the temp table. One
+**   (current) that points to the next row to return to the query engine
+**   once its window function values have been calculated. Another (end)
+**   points to the next row to call the xStep() method of each window function
+**   on (so that it is 2 groups ahead of current). And a third (start) that
+**   points to the next row to call the xInverse() method of each window
+**   function on.
+**
+**   Each cursor (start, current and end) consists of a VDBE cursor
+**   (WindowCsrAndReg.csr) and an array of registers (starting at
+**   WindowCodeArg.reg) that always contains a copy of the peer values 
+**   read from the corresponding cursor.
+**
+**   Depending on the window-frame in question, all three cursors may not
+**   be required. In this case both WindowCodeArg.csr and reg are set to
+**   0.
+*/
 struct WindowCodeArg {
-  Parse *pParse;
+  Parse *pParse;             /* Parse context */
-  Window *pMWin;
+  Window *pMWin;             /* First in list of functions being processed */
-  Vdbe *pVdbe;
+  Vdbe *pVdbe;               /* VDBE object */
-  int regGosub;
+  int addrGosub;             /* OP_Gosub to this address to return one row */
-  int addrGosub;
+  int regGosub;              /* Register used with OP_Gosub(addrGosub) */
-  int regArg;
+  int regArg;                /* First in array of accumulator registers */
-  int eDelete;
+  int eDelete;               /* See above */
 
   WindowCsrAndReg start;
   WindowCsrAndReg current;
@@ -1876,18 +1935,18 @@ static void windowIfNewPeer(
 */
 static void windowCodeRangeTest(
   WindowCodeArg *p, 
-  int op,                          /* OP_Ge, OP_Gt, or OP_Le */
+  int op,                         /* OP_Ge, OP_Gt, or OP_Le */
-  int csr1,                        /* Cursor number for cursor 1 */
+  int csr1,                       /* Cursor number for cursor 1 */
-  int regVal,                      /* Register containing non-negative number */
+  int regVal,                     /* Register containing non-negative number */
-  int csr2,                        /* Cursor number for cursor 2 */
+  int csr2,                       /* Cursor number for cursor 2 */
-  int lbl                          /* Jump destination if the condition is true */
+  int lbl                         /* Jump destination if condition is true */
 ){
   Parse *pParse = p->pParse;
   Vdbe *v = sqlite3GetVdbe(pParse);
-  ExprList *pOrderBy = p->pMWin->pOrderBy;  /* ORDER BY clause for this window */
+  ExprList *pOrderBy = p->pMWin->pOrderBy;  /* ORDER BY clause for window */
-  int reg1 = sqlite3GetTempReg(pParse);     /* Register for csr1.peerVal+regVal */
+  int reg1 = sqlite3GetTempReg(pParse);     /* Reg. for csr1.peerVal+regVal */
-  int reg2 = sqlite3GetTempReg(pParse);     /* Regiser for csr2.peerVal */
+  int reg2 = sqlite3GetTempReg(pParse);     /* Reg. for csr2.peerVal */
-  int regString = ++pParse->nMem;           /* Register for constant value '' */
+  int regString = ++pParse->nMem;           /* Reg. for constant value '' */
   int arith = OP_Add;                       /* OP_Add or OP_Subtract */
   int addrGe;                               /* Jump destination */