lsup_rdf/include/store_htable.h

/** @file store.htable.h
 *
 * @brief Simple in-memory triple store back end based on hash tables.
 *
 * This is the simplest choice to do in-memory manipulation of RDF graphs and
 * it has some limitations: most notably, it only supports triples without
 * context (one graph per store) and it is not indexed. This means that it is
 * optimized for fast writes and sequential lookups (iteration). Lookups on
 * arbitrary terms are supported but require iterating over all the triples.
 * This implementation is most convenient for graphs where retrieval is done
 * via iteration.
 *
 * Also, as it may be obvious, this store is not persistent.
 *
 * For faster random lookups and persistence, the MDB backend is preferred. If
 * persistence is not required (e.g. ingesting and manipulating a very large
 * graph and outputting some results on a file) an ad-hoc MDB store located in
 * RAM disk can be used, which is much faster.
 */
#ifndef _LSUP_STORE_HTABLE_H
#define _LSUP_STORE_HTABLE_H

#include "buffer.h"


typedef struct ht_store_t LSUP_HTStore;
typedef struct ht_iterator_t LSUP_HTIterator;

LSUP_HTStore *
LSUP_htstore_new (void);


/** @brief Boolean operation on hash table triples.
 *
 * The resulting store is compacted to the minimum size necessary to hold all
 * results.
 *
 * @param[in] op Operation type. See #LSUP_bool_op
 *
 * @param[in] s1 First store.
 *
 * @param[in] s2 Second store.
 *
 * @return New store resulting from the operation. It must be freed with
 * #LSUP_htstore_free after use.
 */
LSUP_HTStore *
LSUP_htstore_bool_op (
        const LSUP_bool_op op, const LSUP_HTStore *s1, const LSUP_HTStore *s2);


/** @brief Free a hash table store.
 */
void
LSUP_htstore_free (LSUP_HTStore *ht);


/** @brief Copy contents of a store to another store.
 *
 * The destination is not initialized, so copy is cumulative with the existing
 * content.
 *
 * @param[in] Store to copy to. It must be already initialized via
 *  #LSUP_htstore_new(), #LSUP_HTstore_copy(), etc.
 *
 * @param[in] src Store to copy from.
 */
LSUP_rc
LSUP_htstore_copy_contents (LSUP_HTStore *dest, const LSUP_HTStore *src);


/** Add a term to the index.
 *
 * @parm[in] store HTStore handle.
 *
 * @param[in] sterm Serialized term to insert.
 *
 * @return LSUP_OK on success; LSUP_NOACTION if the term exists already; <0
 *  on error.
 */
LSUP_rc
LSUP_htstore_add_term (LSUP_HTStore *store, const LSUP_Buffer *sterm);


LSUP_HTIterator *
LSUP_htstore_add_init (LSUP_HTStore *store);


/** @brief Add triples to the store.
 *
 * @param[in] store Store handle.
 *
 * @param[in] sspo Triples to add, serialized into buffer triples.
 */
LSUP_rc
LSUP_htstore_add_iter (LSUP_HTIterator *it, const LSUP_BufferTriple *sspo);


void
LSUP_htstore_add_done (LSUP_HTIterator *it);


LSUP_rc
LSUP_htstore_remove(
        LSUP_HTStore *store, const LSUP_Buffer *ss, const LSUP_Buffer *sp,
        const LSUP_Buffer *so, size_t *ct);

LSUP_HTIterator *
LSUP_htstore_lookup(
        LSUP_HTStore *store, const LSUP_Buffer *ss, const LSUP_Buffer *sp,
        const LSUP_Buffer *so);

size_t
LSUP_htstore_size (LSUP_HTStore *ht);

void
LSUP_htiter_free (LSUP_HTIterator *it);

size_t
LSUP_htiter_cur (LSUP_HTIterator *it);

LSUP_rc
LSUP_htiter_next (LSUP_HTIterator *it, LSUP_BufferTriple *sspo);

#endif  // _LSUP_STORE_HTABLE_H