X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=lib%2Fdatabase.cc;h=6842fafadad86967b4363abd5869a2aeaef345c2;hb=6847960a585b9816907b313e54e7572e0fdfdc85;hp=2511caec7a8623e36c20ba92d32613f28f662ae7;hpb=f8dc5c08e4479c244e0835e87d4b487a436042e0;p=notmuch

diff --git a/lib/database.cc b/lib/database.cc
index 2511caec..6842fafa 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,22 +1313,21 @@ _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 (*thread_id == NULL) {
-		*thread_id = talloc_strdup (message, parent_thread_id);
-		_notmuch_message_add_term (message, "thread", *thread_id);
-	    } else if (strcmp (*thread_id, parent_thread_id)) {
-		ret = _merge_threads (notmuch, *thread_id, parent_thread_id);
-		if (ret)
-		    goto DONE;
-	    }
+	if (*thread_id == NULL) {
+	    *thread_id = talloc_strdup (message, parent_thread_id);
+	    _notmuch_message_add_term (message, "thread", *thread_id);
+	} else if (strcmp (*thread_id, parent_thread_id)) {
+	    ret = _merge_threads (notmuch, *thread_id, parent_thread_id);
+	    if (ret)
+		goto DONE;
 	}
     }
 
@@ -1376,17 +1419,27 @@ _notmuch_database_link_message (notmuch_database_t *notmuch,
 				notmuch_message_file_t *message_file)
 {
     notmuch_status_t status;
-    const char *thread_id = NULL;
-    char *metadata_key = _get_metadata_thread_id_key (message,
-            notmuch_message_get_message_id (message));
+    const char *message_id, *thread_id = NULL;
+    char *metadata_key;
+    string stored_id;
+
+    message_id = notmuch_message_get_message_id (message);
+    metadata_key = _get_metadata_thread_id_key (message, message_id);
+
     /* Check if we have already seen related messages to this one.
      * If we have then use the thread_id that we stored at that time.
      */
-    string stored_id = notmuch->xapian_db->get_metadata (metadata_key);
-    if (!stored_id.empty()) {
-        Xapian::WritableDatabase *db = static_cast <Xapian::WritableDatabase *> (notmuch->xapian_db);
+    stored_id = notmuch->xapian_db->get_metadata (metadata_key);
+    if (! stored_id.empty()) {
+        Xapian::WritableDatabase *db;
+
+	db = static_cast <Xapian::WritableDatabase *> (notmuch->xapian_db);
+
+	/* Clear the metadata for this message ID. We don't need it
+	 * anymore. */
         db->set_metadata (metadata_key, "");
         thread_id = stored_id.c_str();
+
         _notmuch_message_add_term (message, "thread", thread_id);
     }
     talloc_free (metadata_key);