X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=lib%2Fdatabase.cc;h=ff6f100db98f6db7e4ae237b9c3efb4dfc33093b;hb=071022c253a6c2fbf445478619d1a32d945be438;hp=39cbc68342eccb58d93f7534fe6a30c43bedbc5a;hpb=af49741228ec1582c83e266dbb8d6551f015d610;p=notmuch

diff --git a/lib/database.cc b/lib/database.cc
index 39cbc683..ff6f100d 100644
--- a/lib/database.cc
+++ b/lib/database.cc
@@ -44,7 +44,8 @@ typedef struct {
 
 /* Here's the current schema for our database (for NOTMUCH_DATABASE_VERSION):
  *
- * We currently have two different types of documents: mail and directory.
+ * We currently have two different types of documents (mail and
+ * directory) and also some metadata.
  *
  * Mail document
  * -------------
@@ -118,6 +119,49 @@ typedef struct {
  *
  * The data portion of a directory document contains the path of the
  * directory (relative to the database path).
+ *
+ * Database metadata
+ * -----------------
+ * Xapian allows us to store arbitrary name-value pairs as
+ * "metadata". We currently use the following metadata names with the
+ * given meanings:
+ *
+ *	version		The database schema version, (which is distinct
+ *			from both the notmuch package version (see
+ *			notmuch --version) and the libnotmuch library
+ *			version. The version is stored as an base-10
+ *			ASCII integer. The initial database version
+ *			was 1, (though a schema existed before that
+ *			were no "version" database value existed at
+ *			all). Succesive versions are allocated as
+ *			changes are made to the database (such as by
+ *			indexing new fields).
+ *
+ *	last_thread_id	The last thread ID generated. This is stored
+ *			as a 16-byte hexadecimal ASCII representation
+ *			of a 64-bit unsigned integer. The first ID
+ *			generated is 1 and the value will be
+ *			incremented for each thread ID.
+ *
+ *	thread_id_*	A pre-allocated thread ID for a particular
+ *			message. This is actually an arbitarily large
+ *			family of metadata name. Any particular name
+ *			is formed by concatenating "thread_id_" with a
+ *			message ID. The value stored is a thread ID.
+ *
+ *			These thread ID metadata values are stored
+ *			whenever a message references a parent message
+ *			that does not yet exist in the database. A
+ *			thread ID will be allocated and stored, and if
+ *			the message is later added, the stored thread
+ *			ID will be used (and the metadata value will
+ *			be cleared).
+ *
+ *			Even before a message is added, it's
+ *			pre-allocated thread ID is useful so that all
+ *			descendant messages that reference this common
+ *			parent can be recognized as belonging to the
+ *			same thread.
  */
 
 /* With these prefix values we follow the conventions published here:
@@ -1269,14 +1313,15 @@ _notmuch_database_link_message_to_parents (notmuch_database_t *notmuch,
 	const char *parent_thread_id;
 
 	parent_message_id = (char *) l->data;
+
+	_notmuch_message_add_term (message, "reference",
+				   parent_message_id);
+
 	parent_thread_id = _resolve_message_id_to_thread_id (notmuch,
 							     message,
 							     parent_message_id);
 
-	if (parent_thread_id == NULL) {
-	    _notmuch_message_add_term (message, "reference",
-				       parent_message_id);
-	} else {
+	if (parent_thread_id != NULL) {
 	    if (*thread_id == NULL) {
 		*thread_id = talloc_strdup (message, parent_thread_id);
 		_notmuch_message_add_term (message, "thread", *thread_id);