Improvements to comments. Store some extra information in SqliteThread that

is useful for debugging.

FossilOrigin-Name: 9fb5e212089d85cdd3b4787dd69c72e6d84560b6

manifest

@@ -1,5 +1,5 @@
-C Merge\sall\srecent\strunk\schanges\sinto\sthe\sthreads\sbranch.
-D 2014-04-23T12:57:55.344
+C Improvements\sto\scomments.\s\sStore\ssome\sextra\sinformation\sin\sSqliteThread\sthat\nis\suseful\sfor\sdebugging.
+D 2014-04-24T12:28:28.628
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in ad0921c4b2780d01868cf69b419a4f102308d125
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -272,7 +272,7 @@ F src/test_thread.c 1e133a40b50e9c035b00174035b846e7eef481cb
 F src/test_vfs.c e72f555ef7a59080f898fcf1a233deb9eb704ea9
 F src/test_vfstrace.c 3a0ab304682fecbceb689e7d9b904211fde11d78
 F src/test_wsd.c 41cadfd9d97fe8e3e4e44f61a4a8ccd6f7ca8fe9
-F src/threads.c b8e7232f2b9c9d148d6886117160de394d172f85
+F src/threads.c e35de159f9ced746266ff4b2129b7a828e59119c
 F src/tokenize.c 6da2de6e12218ccb0aea5184b56727d011f4bee7
 F src/trigger.c 66f3470b03b52b395e839155786966e3e037fddb
 F src/update.c 5b3e74a03b3811e586b4f2b4cbd7c49f01c93115
@@ -286,7 +286,7 @@ F src/vdbeapi.c 0ed6053f947edd0b30f64ce5aeb811872a3450a4
 F src/vdbeaux.c 8289ed68e2262844334461ccb1b91c4d55b29b0b
 F src/vdbeblob.c 9205ce9d3b064d9600f8418a897fc88b5687d9ac
 F src/vdbemem.c 6fc77594c60f6155404f3f8d71bf36d1fdeb4447
-F src/vdbesort.c f93c8aaff5398a702a7b49aae128031e050300b9
+F src/vdbesort.c 2b13026e5d4afa4737a312715aa1cd7e2f4d07c2
 F src/vdbetrace.c 6f52bc0c51e144b7efdcfb2a8f771167a8816767
 F src/vtab.c 21b932841e51ebd7d075e2d0ad1415dce8d2d5fd
 F src/wal.c 76e7fc6de229bea8b30bb2539110f03a494dc3a8
@@ -1165,7 +1165,7 @@ F tool/vdbe_profile.tcl 67746953071a9f8f2f668b73fe899074e2c6d8c1
 F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4
 F tool/warnings.sh d1a6de74685f360ab718efda6265994b99bbea01
 F tool/win/sqlite.vsix 030f3eeaf2cb811a3692ab9c14d021a75ce41fff
-P 5fce40c44aacf883df2e8e9472c399a6e92197b3 65d2544af9adc1e2f1d193e57f8be0422fb0d5eb
-R 07151f40a802d55a98a20acba34885fa
+P e2c9f71a451e44040624b9f255b4510743513019
+R 85ab93c26e2f3dfc5f24d719f3aa0846
 U drh
-Z 85be1e117efe898356ded29b053b1ff8
+Z 26e90d38e785197a28b1e4097f1c9b04

manifest.uuid

@@ -1 +1 @@
-e2c9f71a451e44040624b9f255b4510743513019
+9fb5e212089d85cdd3b4787dd69c72e6d84560b6

src/threads.c

@@ -37,9 +37,11 @@
 
 /* A running thread */
 struct SQLiteThread {
-  pthread_t tid;
-  int done;
-  void *pOut;
+  pthread_t tid;                 /* Thread ID */
+  int done;                      /* Set to true when thread finishes */
+  void *pOut;                    /* Result returned by the thread */
+  void *(*xTask)(void*);         /* The thread routine */
+  void *pIn;                     /* Argument to the thread */
 };
 
 /* Create a new thread */
@@ -56,6 +58,8 @@ int sqlite3ThreadCreate(
   p = sqlite3Malloc(sizeof(*p));
   if( p==0 ) return SQLITE_NOMEM;
   memset(p, 0, sizeof(*p));
+  p->xTask = xTask;
+  p->pIn = pIn;
   if( sqlite3GlobalConfig.bCoreMutex==0
     || pthread_create(&p->tid, 0, xTask, pIn)!=0 
   ){

src/vdbesort.c

@@ -15,7 +15,7 @@
 ** using indexes and without LIMIT clauses.
 **
 ** The VdbeSorter object implements a multi-threaded external merge sort
-** algorithm that is efficient even if the number of element being sorted
+** algorithm that is efficient even if the number of elements being sorted
 ** exceeds the available memory.
 **
 ** Here is the (internal, non-API) interface between this module and the
@@ -104,9 +104,7 @@
 **
 ** When Rewind() is called, any data remaining in memory is flushed to a 
 ** final PMA. So at this point the data is stored in some number of sorted
-** PMAs within temporary files on disk. Within a single file sorter is 
-** running in single threaded mode, or distributed between one or more files
-** for multi-threaded sorters.
+** PMAs within temporary files on disk.
 **
 ** If there are fewer than SORTER_MAX_MERGE_COUNT PMAs in total and the
 ** sorter is running in single-threaded mode, then these PMAs are merged
@@ -158,7 +156,7 @@ typedef struct SorterRecord SorterRecord;   /* A record being sorted */
 typedef struct SortSubtask SortSubtask;     /* A sub-task in the sort process */
 typedef struct SorterFile SorterFile;       /* Temporary file object wrapper */
 typedef struct SorterList SorterList;       /* In-memory list of records */
-typedef struct IncrMerger IncrMerger;
+typedef struct IncrMerger IncrMerger;       /* Read & merge multiple PMAs */
 
 /*
 ** A container for a temp file handle and the current amount of data 
@@ -170,11 +168,16 @@ struct SorterFile {
 };
 
 /*
-** In memory linked list of records.
+** An in-memory list of objects to be sorted.
+**
+** If aMemory==0 then each object is allocated separately and the objects
+** are connected using SorterRecord.u.pNext.  If aMemory!=0 then all objects
+** are stored in the aMemory[] bulk memory, one right after the other, and
+** are connected using SorterRecord.u.iNext.
 */
 struct SorterList {
   SorterRecord *pList;            /* Linked list of records */
-  u8 *aMemory;                    /* If non-NULL, blob of memory for pList */
+  u8 *aMemory;                    /* If non-NULL, bulk memory to hold pList */
   int szPMA;                      /* Size of pList as PMA in bytes */
 };