Comment changes only: Add several optimization marks in rowset.c. Add

a header comment that explains what the various special comments mean.

FossilOrigin-Name: 8cdbe89ac6c22d632f677eb293111b3dbae7d6c1

2 files changed, 41 insertions, 7 deletions

diff --git a/src/rowset.c b/src/rowset.c
index bf4382ddd..5420ab991 100644
--- a/src/rowset.c
+++ b/src/rowset.c
@@ -179,7 +179,9 @@ void sqlite3RowSetClear(RowSet *p){
 */
 static struct RowSetEntry *rowSetEntryAlloc(RowSet *p){
   assert( p!=0 );
-  if( p->nFresh==0 ){
+  if( p->nFresh==0 ){  /*OPTIMIZATION-IF-FALSE*/
+    /* We could allocate a fresh RowSetEntry each time one is needed, but it
+    ** is more efficient to pull a preallocated entry from the pool */
     struct RowSetChunk *pNew;
     pNew = sqlite3DbMallocRawNN(p->db, sizeof(*pNew));
     if( pNew==0 ){
@@ -213,7 +215,9 @@ void sqlite3RowSetInsert(RowSet *p, i64 rowid){
   pEntry->pRight = 0;
   pLast = p->pLast;
   if( pLast ){
-    if( (p->rsFlags & ROWSET_SORTED)!=0 && rowid<=pLast->v ){
+    if( rowid<=pLast->v ){  /*OPTIMIZATION-IF-FALSE*/
+      /* Avoid unnecessary sorts by preserving the ROWSET_SORTED flags
+      ** where possible */
       p->rsFlags &= ~ROWSET_SORTED;
     }
     pLast->pRight = pEntry;
@@ -335,16 +339,19 @@ static struct RowSetEntry *rowSetNDeepTree(
 ){
   struct RowSetEntry *p;         /* Root of the new tree */
   struct RowSetEntry *pLeft;     /* Left subtree */
-  if( *ppList==0 ){
-    return 0;
+  if( *ppList==0 ){ /*OPTIMIZATION-IF-TRUE*/
+    /* Prevent unnecessary deep recursion when we run out of entries */
+    return 0; 
   }
   if( iDepth>1 ){   /*OPTIMIZATION-IF-TRUE*/
     /* This branch causes a *balanced* tree to be generated.  A valid tree
-    ** is still generated without this branch, but it is wildly unbalanced
-    ** and inefficient. */
+    ** is still generated without this branch, but the tree is wildly
+    ** unbalanced and inefficient. */
     pLeft = rowSetNDeepTree(ppList, iDepth-1);
     p = *ppList;
-    if( p==0 ){
+    if( p==0 ){     /*OPTIMIZATION-IF-FALSE*/
+      /* It is safe to always return here, but the resulting tree
+      ** would be unbalanced */
       return pLeft;
     }
     p->pLeft = pLeft;
diff --git a/src/sqliteInt.h b/src/sqliteInt.h
index 7bb15d0bf..76bf80962 100644
--- a/src/sqliteInt.h
+++ b/src/sqliteInt.h
@@ -15,6 +15,33 @@
 #ifndef _SQLITEINT_H_
 #define _SQLITEINT_H_
 
+/* Special Comments:
+**
+** Some comments have special meaning to the tools that measure test
+** coverage:
+**
+**    NO_TEST                     - The branches on this line are not
+**                                  measured by branch coverage.  This is
+**                                  used on lines of code that actually
+**                                  implement parts of coverage testing.
+**
+**    OPTIMIZATION-IF-TRUE        - This branch is allowed to alway be false
+**                                  and the correct answer is still obtained,
+**                                  though perhaps more slowly.
+**
+**    OPTIMIZATION-IF-FALSE       - This branch is allowed to alway be true
+**                                  and the correct answer is still obtained,
+**                                  though perhaps more slowly.
+**
+**    PREVENTS-HARMLESS-OVERREAD  - This branch prevents a buffer overread
+**                                  that would be harmless and undetectable
+**                                  if it did occur.  
+**
+** In all cases, the special comment must be enclosed in the usual
+** slash-asterisk...asterisk-slash comment marks, with no spaces between the 
+** asterisks and the comment text.
+*/
+
 /*
 ** Make sure that rand_s() is available on Windows systems with MSVC 2005
 ** or higher.