Add destroy functions for results, message, and tags.

None of these are strictly necessary, (everything was leak-free
without them), but notmuch_message_destroy can actually be useful
for when one query has many message results, but only one is needed
to be live at a time.

The destroy functions for results and tags are fairly gratuitous, as
there's unlikely to be any benefit from calling them. But they're all
easy to add, (all of these functions are just wrappers for talloc_free),
and we do so for consistency and completeness.

diff --git a/message.cc b/message.cc
index cc157c8b010f3f5aaa0c0f9675639da12d10e1ec..ca4a16c79bc941c3be27299af8615fd85f90ccf0 100644 (file)
--- a/message.cc
+++ b/message.cc
@@ -115,6 +115,12 @@ notmuch_message_get_tags (notmuch_message_t *message)
     return tags;
 }
 
+void
+notmuch_message_destroy (notmuch_message_t *message)
+{
+    talloc_free (message);
+}
+
 notmuch_bool_t
 notmuch_tags_has_more (notmuch_tags_t *tags)
 {
@@ -141,3 +147,9 @@ notmuch_tags_advance (notmuch_tags_t *tags)
 {
     tags->iterator++;
 }
+
+void
+notmuch_tags_destroy (notmuch_tags_t *tags)
+{
+    talloc_free (tags);
+}

diff --git a/notmuch.h b/notmuch.h
index 6d81fb6ca08a0a0601a767d5238c39badbb9994d..10067d3fb499b271bdbd01e6ec7f11b0b520e4e0 100644 (file)
--- a/notmuch.h
+++ b/notmuch.h
@@ -226,8 +226,13 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  *
  *     notmuch_query_destroy (query);
  *
- * Note that there's no explicit destructor for the notmuch_results_t
- * object.
+ * Note that there's no explicit destructor needed for the
+ * notmuch_results_t object.
+ *
+ * (For consistency, we do provide a notmuch_results_destroy function,
+ * but there's no point in calling it if you're about to destroy the
+ * query object as well too---either call will free all the memory of
+ * the results).
  */
 notmuch_results_t *
 notmuch_query_search (notmuch_query_t *query);
@@ -272,6 +277,15 @@ notmuch_results_get (notmuch_results_t *results);
 void
 notmuch_results_advance (notmuch_results_t *results);
 
+/* Destroy a notmuch_results_t object.
+ *
+ * It's not strictly necessary to call this function. All memory from
+ * the notmuch_results_t object will be reclaimed when the containg
+ * query object is destroyed.
+ */
+void
+notmuch_results_destroy (notmuch_results_t *results);
+
 /* Get the message ID of 'message'.
  *
  * The returned string belongs to 'message' and as such, should not be
@@ -305,12 +319,25 @@ notmuch_message_get_message_id (notmuch_message_t *message);
  *         ....
  *     }
  *
- * Note that there's no explicit destructor for the notmuch_tags_t
- * object.
+ * Note: If you are finished with a message before its containing
+ * query, you can call notmuch_message_destroy to clean up some memory
+ * sooner. If you don't call it, all the memory will still be
+ * reclaimed when the query is destroyed.
  */
 notmuch_tags_t *
 notmuch_message_get_tags (notmuch_message_t *message);
 
+/* Destroy a notmuch_message_t object.
+ *
+ * It can be useful to call this function in the case of a single
+ * query object with many messages in the result, (such as iterating
+ * over the entire database). Otherwise, it's fine to never call this
+ * function and there will still be no memory leaks. (The memory from
+ * the messages get reclaimed when the containing query is destroyed.)
+ */
+void
+notmuch_message_destroy (notmuch_message_t *message);
+
 /* Does the given notmuch_tags_t object contain any more results.
  *
  * When this function returns TRUE, notmuch_tags_get will return a
@@ -342,6 +369,15 @@ notmuch_tags_get (notmuch_tags_t *tags);
 void
 notmuch_tags_advance (notmuch_tags_t *results);
 
+/* Destroy a notmuch_tags_t object.
+ *
+ * It's not strictly necessary to call this function. All memory from
+ * the notmuch_tags_t object will be reclaimed when the containg
+ * message or query objects are destroyed.
+ */
+void
+notmuch_tags_destroy (notmuch_tags_t *tags);
+
 NOTMUCH_END_DECLS
 
 #endif

diff --git a/query.cc b/query.cc
index c669fb9110a6fed7347ae454ddafa12fac3edbaa..2a1815a748425f34fb20a8e210cd311ec10c1d9d 100644 (file)
--- a/query.cc
+++ b/query.cc
@@ -141,3 +141,9 @@ notmuch_results_advance (notmuch_results_t *results)
 {
     results->iterator++;
 }
+
+void
+notmuch_results_destroy (notmuch_results_t *results)
+{
+    talloc_free (results);
+}