lsup_rdf/include/lsup/store.h

/** @file store.h
 *
 * @brief Generic store dependency.
 *
 * This code allows to use the store interface with any supported back end
 * without any knowledge of the back end implementations. Code using the store
 * interface need only include this file.
 *
 * New store implementations should be added to this file as `#include`s as
 * well as entries in the `BACKEND_TBL` macro.
 */

#ifndef _LSUP_STORE_H
#define _LSUP_STORE_H

/*
 * Add new back end headers here.
 */
#include "lsup/store_htable.h"
#include "lsup/store_mdb.h"

/** @defgroup store Backend store module
 * @ingroup public
 * @{
 */

/*
 * Define backend types.
 *
 * Add new store implementations to this table.
 */
#define BACKEND_TBL                                                           \
/*          #enum suffix#store if       */\
    ENTRY(  HTABLE,     htstore_int  )  \
    ENTRY(  MDB,        mdbstore_int ) \


/// Store types. All prefixed with `LSUP_STORE_`.
typedef enum {
#define ENTRY(a, b) \
    LSUP_STORE_##a,
BACKEND_TBL
#undef ENTRY
} LSUP_StoreType;


/** @brief Store structure.
 *
 * Code using the store interface should create an instance of this structure
 * with pointers to the store interface of their choice, and to an opaque
 * structure to hold the store state.
 *
 * Iterator state handles generated by lookup and add functions are kept
 * outside of this structure, but manipulated by the interface specified in
 * here.
 *
 * @sa #LSUP_graph_new()
 */
typedef struct store_t {
    LSUP_StoreType                  type;   ///< Store type.
    char *                          id;     /**< Store ID.
                                             *
                                             *   NOTE: This is
                                             *   NULL for volatile stores.
                                             */
    const LSUP_StoreInt *           sif;    ///< Store interface.
    void *                          data;   ///< Store back end data.
} LSUP_Store;


/** @brief Return store interface for a specific type.
 */
const LSUP_StoreInt *
LSUP_store_int (LSUP_StoreType type);


/** @brief Return the store type label.
 *
 * @param type Store type enum.
 *
 * @return Store type label as `STORE_<type>`.
 */
const char *
LSUP_store_type_label (LSUP_StoreType type);


/** @brief Create a new store.
 *
 * The life cycle of a store may normally outspan the one of one or multiple
 * graphs with the same back end, hence it is managed independently.
 *
 * @param[in] store_type Type of store backing the graph. One of the values of
 *  #LSUP_StoreType.
 *
 * @param[in] store_id Identifier for the store. This may be
 *  interpreted differently by each store implementation. For the MDB store,
 *  this is the file path where the store is located. It is ignored by volatile
 *  stores (with LSUP_STORE_PERM feature flag set to false). If a store
 *  does not exist for the given identifier, a new one is initialized. If this
 *  parameter is NULL, the default store for the selected type is used.
 *
 *  @param[in] size Initial size of the store. Only used for optimization
 *  purposes. It may be ignored by some implementations and it is always safe
 *  to set to 0.
 *
 *  @param clear Flag that is passed to the `init_fn` function of the store
 *   interface, if present, to clear an existing store with the same ID.
 *
 *  @return Store handle. It must be freed with #LSUP_store_free().
 */
LSUP_Store *
LSUP_store_new (
        const LSUP_StoreType store_type, const char *store_id, size_t size,
        bool clear);


/** @brief Free a store created with #LSUP_store_new().
 *
 * @param[in] store Store handle.
 */
void
LSUP_store_free (LSUP_Store *store);


/** @brief Begin a transaction.
 *
 * If the store supports it, begin a transaction. Only one transaction may be
 * opened at a time.
 *
 * The transaction must be either committed with #LSUP_store_commit() or
 * rolled back with #LSUP_store_abort().
 *
 * @param[in] store Store handle.
 *
 * @param[in] flags Unused for now, use 0. TODO
 *
 * @param[out] txn Address to be populated with the new transaction handle.
 *
 * @return LSUP_OK on success; LSUP_VALUE_ERR if the store does not
 *  support transactions; LSUP_TXN_ERR if the store has already an uncommitted
 *  transaction; <0 on other errors.
 */
LSUP_rc
LSUP_store_begin (LSUP_Store *store, int flags, void **txn);


/** @brief Commit a transaction.
 *
 * If the store supports it, commit an open transaction. In case of
 * error, the transaction is left open and it is advisable to roll it back with
 * #LSUP_store_abort().
 *
 * @param[in] store Store handle.
 *
 * @param[in] txn transaction handle to commit.
 *
 * @return LSUP_OK if the transaction was committed successfully; LSUP_NOACTION
 *  if NULL was passed; LSUP_TXN_ERR on error.
 */
LSUP_rc
LSUP_store_commit (LSUP_Store *store, void *txn);


/** @brief Abort (roll back) a transaction.
 *
 * If the store supports it, abort an open transaction and abandon all changes.
 *
 * @param[in] store Store handle.
 *
 * @param[in] txn transaction handle to abort.
 */
void
LSUP_store_abort (LSUP_Store *store, void *txn);

/// @}  END store
#endif  /* LSUP_STORE_H */