Split notmuch_database_close into two functions

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 673c4237ca4f98ba18183cf2c62ee4f0cd785f0d..7d9e0921f0c17e9f442f46e57dcc33e152c13329 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -133,7 +133,7 @@ typedef struct _notmuch_filenames notmuch_filenames_t;
  *
  * After a successful call to notmuch_database_create, the returned
  * database will be open so the caller should call
  *
  * After a successful call to notmuch_database_create, the returned
  * database will be open so the caller should call

- * notmuch_database_close when finished with it.
+ * notmuch_database_destroy when finished with it.

  *
  * The database will not yet have any data in it
  * (notmuch_database_create itself is a very cheap function). Messages
  *
  * The database will not yet have any data in it
  * (notmuch_database_create itself is a very cheap function). Messages


@@ -165,7 +165,7 @@ typedef enum {
  * An existing notmuch database can be identified by the presence of a
  * directory named ".notmuch" below 'path'.
  *
  * An existing notmuch database can be identified by the presence of a
  * directory named ".notmuch" below 'path'.
  *

- * The caller should call notmuch_database_close when finished with
+ * The caller should call notmuch_database_destroy when finished with

  * this database.
  *
  * In case of any failure, this function returns NULL, (after printing
  * this database.
  *
  * In case of any failure, this function returns NULL, (after printing


@@ -175,11 +175,25 @@ notmuch_database_t *
 notmuch_database_open (const char *path,
                       notmuch_database_mode_t mode);
 
 notmuch_database_open (const char *path,
                       notmuch_database_mode_t mode);
 

-/* Close the given notmuch database, freeing all associated
- * resources. See notmuch_database_open. */
+/* Close the given notmuch database.
+ *
+ * After notmuch_database_close has been called, calls to other
+ * functions on objects derived from this database may either behave
+ * as if the database had not been closed (e.g., if the required data
+ * has been cached) or may fail with a
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION.
+ *
+ * notmuch_database_close can be called multiple times.  Later calls
+ * have no effect.
+ */

 void
 notmuch_database_close (notmuch_database_t *database);
 
 void
 notmuch_database_close (notmuch_database_t *database);
 

+/* Destroy the notmuch database, closing it if necessary and freeing
+* all associated resources. */
+void
+notmuch_database_destroy (notmuch_database_t *database);
+

 /* Return the database path of the given database.
  *
  * The return value is a string owned by notmuch so should not be
 /* Return the database path of the given database.
  *
  * The return value is a string owned by notmuch so should not be