|
@@ -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 point to the new open transaction on success, or to
|
|
|
+ * undefined content 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 handle generated by #store_txn_begin_fn_t.
|
|
|
+ */
|
|
|
+typedef void (*store_txn_abort_fn_t)(void *store);
|
|
|
|
|
|
|
|
|
/** @brief Initialize bulk triple load.
|
|
@@ -143,9 +186,13 @@ typedef LSUP_rc (*store_stat_fn_t)(void *store, void *stat);
|
|
|
* the value of sc, triples will be added with no context. Only meaningful
|
|
|
* for stores with the LSUP_STORE_CTX feature.
|
|
|
*
|
|
|
+ * @param[in] udata User data. Consult individual store implementations for
|
|
|
+ * how this is interpreted.
|
|
|
+ *
|
|
|
* @return Iterator handle to be passed to the following load steps.
|
|
|
*/
|
|
|
-typedef void * (*store_add_init_fn_t)(void *store, const LSUP_Buffer * sc);
|
|
|
+typedef void * (*store_add_init_fn_t)(
|
|
|
+ void *store, const LSUP_Buffer *sc, void *udata);
|
|
|
|
|
|
|
|
|
/** @brief Add one triple into the store.
|
|
@@ -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,11 +219,30 @@ 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);
|
|
|
|
|
|
|
|
|
+/*
|
|
|
+ * Iterator function types.
|
|
|
+ */
|
|
|
+
|
|
|
+/** @brief Get iterator active transaction handle.
|
|
|
+ *
|
|
|
+ * This function is used to get an active transaction during an iteration loop
|
|
|
+ * in order to perform an action using the store state within that loop. Some
|
|
|
+ * stores (e.g. MDB) only support one R/W open transaction per thread, so this
|
|
|
+ * is also the only way to perform anything else than iterating or committing
|
|
|
+ * while a loop is open.
|
|
|
+ *
|
|
|
+ * @param[in] it Iterator handle to get the transaction from.
|
|
|
+ *
|
|
|
+ * @return Transaction handle. DO NOT close this transaction directly.
|
|
|
+ */
|
|
|
+typedef void * (*iter_txn_fn_t)(void *it);
|
|
|
+
|
|
|
+
|
|
|
/** @brief Finalize an add loop and free iterator.
|
|
|
*
|
|
|
* This must be called after #add_iter_fn.
|
|
@@ -192,7 +258,8 @@ typedef LSUP_rc (*store_add_done_fn_t)(void *it);
|
|
|
*
|
|
|
* @param[in] sterm Serialized term to store.
|
|
|
*/
|
|
|
-typedef LSUP_rc (*store_add_term_fn_t)(void *store, const LSUP_Buffer *sterm);
|
|
|
+typedef LSUP_rc (*store_add_term_fn_t)(
|
|
|
+ void *store, const LSUP_Buffer *sterm, void *udata);
|
|
|
|
|
|
|
|
|
/** @brief Prototype: look up triples by pattern matching.
|
|
@@ -200,17 +267,20 @@ typedef LSUP_rc (*store_add_term_fn_t)(void *store, const LSUP_Buffer *sterm);
|
|
|
* This function may return a count of matches and/or an iterator of results as
|
|
|
* serialized triples.
|
|
|
*
|
|
|
+ * For stores with #LSUP_STORE_TXN, this opens a read-only transaction. The
|
|
|
+ * transaction handle is held in the iterator structure and is closed when the
|
|
|
+ * iterator is freed with #iter_free_fn_t().
|
|
|
+ *
|
|
|
* Any and all of the terms may be NULL, which indicates an unbound query
|
|
|
- * term. Stores with context not set or witout context support will always
|
|
|
- * ignore the fourth term.
|
|
|
+ * term. Stores witout context support will always ignore sc.
|
|
|
*
|
|
|
* @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
|
|
@@ -221,6 +291,9 @@ typedef LSUP_rc (*store_add_term_fn_t)(void *store, const LSUP_Buffer *sterm);
|
|
|
* much less so for 1-bound and 2-bound context lookups, in which cases it
|
|
|
* should be set only if needed.
|
|
|
*
|
|
|
+ * @param[in] udata User data. Consult individual store implementations for
|
|
|
+ * how this is interpreted.
|
|
|
+ *
|
|
|
* @return Iterator handle that will be populated with a result iterator. This
|
|
|
* is always created even if no matches are found and must be freed with
|
|
|
* #LSUP_mdbiter_free() after use. If matches are found, the iterator points to
|
|
@@ -229,7 +302,7 @@ typedef LSUP_rc (*store_add_term_fn_t)(void *store, const LSUP_Buffer *sterm);
|
|
|
typedef void * (*store_lookup_fn_t)(
|
|
|
void *store,
|
|
|
const LSUP_Buffer *ss, const LSUP_Buffer *sp, const LSUP_Buffer *so,
|
|
|
- const LSUP_Buffer *sc, size_t *ct);
|
|
|
+ const LSUP_Buffer *sc, void *udata, size_t *ct);
|
|
|
|
|
|
|
|
|
/** @brief Prototype: check for existence of a triple (T/F).
|
|
@@ -250,13 +323,16 @@ typedef bool (*store_trp_exist_fn_t)(
|
|
|
/** @brief Prototype: delete triples by pattern matching.
|
|
|
*
|
|
|
* The ss, sp, so, sc terms act as a matching pattern as documented in
|
|
|
- * #store_lookup_fn. if not NULL, ct yields the number of triples actually
|
|
|
+ * @sa #store_lookup_fn. if not NULL, ct yields the number of triples actually
|
|
|
* deleted.
|
|
|
+ *
|
|
|
+ * @param[in] udata User data. Consult individual store implementations for
|
|
|
+ * how this is interpreted.
|
|
|
*/
|
|
|
typedef LSUP_rc (*store_remove_fn_t)(
|
|
|
void *store,
|
|
|
const LSUP_Buffer *ss, const LSUP_Buffer *sp, const LSUP_Buffer *so,
|
|
|
- const LSUP_Buffer *sc, size_t *ct);
|
|
|
+ const LSUP_Buffer *sc, void *udata, size_t *ct);
|
|
|
|
|
|
|
|
|
/** @brief Put an in-memory namespace map into a permanent back end.
|
|
@@ -278,11 +354,15 @@ typedef LSUP_rc (*store_remove_fn_t)(
|
|
|
*
|
|
|
* @param[out] nsm Namespace map handle to store.
|
|
|
*
|
|
|
+ * @param[in] udata User-defined data. Consult individual implementations for
|
|
|
+ * details.
|
|
|
+ *
|
|
|
* @return LSUP_OK if all terms were updated; LSUP_CONFLICT if one or more
|
|
|
* namespaces or terms were not updated because they already existed; <0 if
|
|
|
* an error occurred.
|
|
|
*/
|
|
|
-typedef LSUP_rc (*store_nsm_put_fn_t)(void *store, const LSUP_NSMap * nsm);
|
|
|
+typedef LSUP_rc (*store_nsm_put_fn_t)(
|
|
|
+ void *store, const LSUP_NSMap * nsm, void *udata);
|
|
|
|
|
|
|
|
|
/** @brief Get the store's namespace prefix map.
|
|
@@ -294,10 +374,6 @@ typedef LSUP_rc (*store_nsm_put_fn_t)(void *store, const LSUP_NSMap * nsm);
|
|
|
typedef LSUP_NSMap * (*store_nsm_get_fn_t)(void *store);
|
|
|
|
|
|
|
|
|
-/*
|
|
|
- * Iterator function types.
|
|
|
- */
|
|
|
-
|
|
|
/** @brief Prototype: yield the matching triples and advance the iterator.
|
|
|
*
|
|
|
* NOTE: Iterators keep transactions open. Don't hold on to them longer than
|
|
@@ -349,6 +425,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,18 +452,26 @@ 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.
|
|
|
+ iter_txn_fn_t iter_txn_fn; ///< Get iterator's transaction.
|
|
|
+
|
|
|
// Addition.
|
|
|
store_add_init_fn_t add_init_fn; ///< Initialize add iteration.
|
|
|
store_add_iter_fn_t add_iter_fn; ///< Add one triple.
|
|
|
- store_add_abort_fn_t add_abort_fn; /**< Abort (roll back) the add
|
|
|
- * process. Only available in
|
|
|
- * stores with #LSUP_STORE_TXN
|
|
|
- * feature. Optional.
|
|
|
+ store_add_abort_fn_t add_abort_fn; /**< Abort (roll back) the add process.
|
|
|
+ *
|
|
|
+ * Only available in
|
|
|
+ * stores with #LSUP_STORE_TXN
|
|
|
+ * feature. Optional.
|
|
|
*/
|
|
|
store_add_done_fn_t add_done_fn; ///< Complete the add process.
|
|
|
store_add_term_fn_t add_term_fn; /**< Add (index) a term to the store.
|
|
|
- * Only available in stores with
|
|
|
- * #LSUP_STORE_IDX feature. Optional.
|
|
|
+ *
|
|
|
+ * Only available in stores with
|
|
|
+ * #LSUP_STORE_IDX feature. Optional.
|
|
|
*/
|
|
|
|
|
|
// Look up.
|
|
@@ -388,14 +484,14 @@ typedef struct store_if_t {
|
|
|
store_remove_fn_t remove_fn; ///< Remove triples by pattern.
|
|
|
|
|
|
// Namespace prefix mapping.
|
|
|
- store_nsm_put_fn_t nsm_put_fn; /**< Add a namespace/prefix pair to
|
|
|
- * the prefix map.
|
|
|
+ store_nsm_put_fn_t nsm_put_fn; /**< Add a ns/pfx pair to the map.
|
|
|
+ *
|
|
|
* Only available (and mandatory)
|
|
|
* in stores with the
|
|
|
* #LSUP_STORE_IDX feature.
|
|
|
*/
|
|
|
- store_nsm_get_fn_t nsm_get_fn; /**< Get a namespace/prefix from
|
|
|
- * the prefix map.
|
|
|
+ store_nsm_get_fn_t nsm_get_fn; /**< Get a namespace from the map.
|
|
|
+ *
|
|
|
* Only available (and mandatory)
|
|
|
* in stores with the
|
|
|
* #LSUP_STORE_IDX feature.
|
|
@@ -417,6 +513,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 +536,4 @@ const LSUP_StoreInt my_store_int = {
|
|
|
};
|
|
|
*/
|
|
|
|
|
|
-#endif /* _LSUP_STORE_BASE_H */
|
|
|
+#endif /* _LSUP_STORE_INTERFACE_H */
|