From: Carl Worth <cworth@cworth.org>
Date: Wed, 21 Oct 2009 05:24:59 +0000 (-0700)
Subject: Add destroy functions for results, message, and tags.
X-Git-Tag: 0.1~806
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=4ca1492f1b6a9172b1dca88aecf1d6e7394ac5d7;p=notmuch.git

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 cc157c8b..ca4a16c7 100644
--- 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 6d81fb6c..10067d3f 100644
--- 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 c669fb91..2a1815a7 100644
--- 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);
+}