Rename store_base header to store_interface.

include/store_htable.h

@@ -21,7 +21,7 @@
 #define _LSUP_STORE_HTABLE_H
 
 #include "buffer.h"
-#include "store_base.h"
+#include "store_interface.h"
 
 
 extern const LSUP_StoreInt htstore_int;

include/store_base.h → include/store_interface.h

@@ -1,4 +1,4 @@
-/** @file store.h
+/** @file store_interface.h
  *
  * @brief Common store back end interfaces.
  *
@@ -32,8 +32,8 @@
  */
 
 
-#ifndef _LSUP_STORE_BASE_H
-#define _LSUP_STORE_BASE_H
+#ifndef _LSUP_STORE_INTERFACE_H
+#define _LSUP_STORE_INTERFACE_H
 
 #include "environment.h"
 
@@ -102,7 +102,7 @@ typedef void (*store_free_fn_t)(void *store);
 
 /** @brief Prototype: get the store ID.
  *
- * @param store[in] Store handle.
+ * @param[in] store  Store handle.
  *
  * @return store ID string. This is a copy and should be freed after use.
  */
@@ -111,22 +111,65 @@ typedef char * (*store_id_fn_t)(const void *store);
 
 /** @brief Prototype: get store size.
  *
- * @param store[in] The store to calculate size of.
+ * @param[in] store  The store to calculate size of.
  *
  * @return Number of stored SPO triples (across all contexts if supported).
  */
 typedef size_t (*store_size_fn_t)(const void *store);
 
 
+#if 0
 /** @brief Print stats about a store.
  *
  * TODO
  *
- * @param store[in] The store to get stats for.
+ * @param[in] store The store to get stats for.
  */
-/* TODO
 typedef LSUP_rc (*store_stat_fn_t)(void *store, void *stat);
-*/
+#endif
+
+
+/** @brief Begin a transaction.
+ *
+ * Only for LSUP_STORE_TXN stores.
+ *
+ * The transaction handle is managed by the store implementation and can be any
+ * data type.
+ *
+ * @param[in] store Store handle.
+ *
+ * @param[in] flags Transaction flags. These vary with each implementation.
+ *
+ * @param[out] txn Will be populated with the new open transaction on success,
+ *  or left undefined on failure.
+ *
+ * @return LSUP_OK if the transaction started successfully, <0 on error.
+ */
+typedef LSUP_rc (*store_txn_begin_fn_t)(void *store, int flags, void **txn);
+
+
+/** @brief Commit a transaction.
+ *
+ * Only for LSUP_STORE_TXN stores.
+ *
+ * @param[in] store Store handle.
+ *
+ * @param[in] txn Transaction handle generated by #store_txn_begin_fn_t.
+ *
+ * @return LSUP_OK if the transaction was committed successfully, <0 on error.
+ */
+typedef LSUP_rc (*store_txn_commit_fn_t)(void *store);
+
+
+/** @brief Abort a transaction.
+ *
+ * Only for LSUP_STORE_TXN stores.
+ *
+ * @param[in] store Store handle.
+ *
+ * @param[in] txn Transaction to abort.
+ */
+typedef void (*store_txn_abort_fn_t)(void *store);
 
 
 /** @brief Initialize bulk triple load.
@@ -135,6 +178,10 @@ typedef LSUP_rc (*store_stat_fn_t)(void *store, void *stat);
  * need to be pre-processed, which can be done in the same loop as the next
  * step to keep memory usage low.
  *
+ * For stores with the #LSUP_STORE_TXN feature, this function should open a
+ * transaction that can be committed with #store_add_done_fn_t or rolled back
+ * with #store_add_abort_fn_t.
+ *
  * @param store[in] The store to add to.
  *
  * @param sc[in] Context as a serialized term. If this is NULL, and the
@@ -154,7 +201,7 @@ typedef void * (*store_add_init_fn_t)(void *store, const LSUP_Buffer * sc);
  * yielded by that function. It may be called multiple times and must be
  * followed by #add_done_fn or #add_abort_fn (if supported).
  *
- * @param it[in] Iterator obtained by #LSUP_mdbstore_add_init.
+ * @param it[in] Iterator obtained by #store_add_init_fn_t.
  *  The following members are of interest:
  *  it->i stores the total number of records inserted.
  *
@@ -172,7 +219,7 @@ typedef LSUP_rc (*store_add_iter_fn_t)(
  * Usually called on an irrecoverable error from #add_iter_fn. None of the
  * successful inserts in the same loop is retained.
  *
- * @param it[in] Iterator obtained by #LSUP_mdbstore_add_init.
+ * @param it[in] Iterator obtained by #store_add_init_fn_t.
  */
 typedef void (*store_add_abort_fn_t)(void *it);
 
@@ -206,11 +253,11 @@ typedef LSUP_rc (*store_add_term_fn_t)(void *store, const LSUP_Buffer *sterm);
  *
  * @param[in] store The store to be queried.
  *
- * @param[in] ss Buffer representing the serialized s term.
+ * @param[in] ss Serialized s term.
  *
- * @param[in] sp Buffer representing the serialized p term.
+ * @param[in] sp Serialized p term.
  *
- * @param[in] so Buffer representing the serialized o term.
+ * @param[in] so Serialized o term.
  *
  * @param[in] sc Serialized context to limit search to. It may be NULL, in
  * which case search is done in all contexts. Note that triples inserted
@@ -349,6 +396,18 @@ typedef void (*iter_free_fn_t)(void * it);
  */
 
 /** @brief Store interface.
+ *
+ * New store implementations should define a static structure with the relevant
+ * members filled in. Some members are only relevant to certain types of stores
+ * and may be set to NULL.
+ *
+ * #setup_fn may be optionally defined and MUST cause an idempotent action,
+ * unless the `clear` argument is set to `true`. Callers should check if this
+ * member is NULL and if it is not, call it at the beginning of the
+ * interaction with the store.
+ *
+ * Transaction control members are only applicable to stores with the
+ * #LSUP_STORE_TXN feature.
  */
 typedef struct store_if_t {
     // Basic properties.
@@ -364,6 +423,11 @@ typedef struct store_if_t {
     store_size_fn_t     size_fn;        ///< Number of triples in the store.
     store_id_fn_t       id_fn;          ///< Get store ID.
 
+    // Transaction control.
+    store_txn_begin_fn_t txn_begin_fn;  ///< Begin transaction.
+    store_txn_commit_fn_t txn_commit_fn; ///< Commit transaction.
+    store_txn_abort_fn_t txn_abort_fn;  ///< Abort transaction.
+
     // Addition.
     store_add_init_fn_t add_init_fn;    ///< Initialize add iteration.
     store_add_iter_fn_t add_iter_fn;    ///< Add one triple.
@@ -417,6 +481,11 @@ const LSUP_StoreInt my_store_int = {
     .free_fn        = my_free_fn,
 
     .size_fn        = my_size_fn,
+    .id_fn          = my_id_fn,
+
+    .txn_begin_fn   = my_txn_begin_fn,
+    .txn_commit_fn  = my_txn_commit_fn,
+    .txn_abort_fn   = my_txn_abort_fn,
 
     .add_init_fn    = my_init_fn,
     .add_iter_fn    = my_iter_fn,
@@ -435,4 +504,4 @@ const LSUP_StoreInt my_store_int = {
 };
 */
 
-#endif  /* _LSUP_STORE_BASE_H */
+#endif  /* _LSUP_STORE_INTERFACE_H */

include/store_mdb.h

@@ -25,10 +25,11 @@
 #include "lmdb.h"
 
 #include "buffer.h"
-#include "store_base.h"
+#include "store_interface.h"
 
 
 // FIXME find a better cross-platform path.
+/// Default MDB store identifier and location.
 #define LSUP_MDB_STORE_URN "file://" TMPDIR "/mdb_store"
 
 /// MDB store interface.