graph.h 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329
  1. #ifndef _LSUP_GRAPH_H
  2. #define _LSUP_GRAPH_H
  3. #include "environment.h"
  4. #include "term.h"
  5. /*
  6. * Define backend types and checks.
  7. */
  8. #define BACKEND_TBL \
  9. ENTRY( MEM, 0)/* Memory backend, hash map. */ \
  10. ENTRY( MDB, 1)/* LMDB back end on persistent disk. */ \
  11. ENTRY( MDB_TMP, 2)/* LMDB back end on RAM disk. */ \
  12. typedef enum LSUP_store_type {
  13. #define ENTRY(a, b) LSUP_STORE_##a = b,
  14. BACKEND_TBL
  15. #undef ENTRY
  16. } LSUP_store_type;
  17. /** @brief Graph object.
  18. */
  19. typedef struct Graph LSUP_Graph;
  20. /** @brief Graph iterator.
  21. *
  22. * This opaque handle is generated by #LSUP_graph_lookup and is used to iterate
  23. * over lookup results with #LSUP_graph_iter_next. It must be freed with
  24. * #LSUP_graph_iter_free when done.
  25. */
  26. typedef struct GraphIterator LSUP_GraphIterator;
  27. /** @brief Create an empty graph.
  28. *
  29. * The new graph has zero capacity and a random URN. To change either one, use
  30. * #LSUP_graph_resize and #LSUP_graph_set_uri, respectively.
  31. *
  32. * The graph is assigned a default (volatile) namespace map if it's in memory,
  33. * hence all graphs share the same namespace map by default. To change this,
  34. * use #LSUP_graph_set_namespace(). MDB graphs use a persistent namespace map
  35. * that is common to all the graphs in the same store. This cannot be changed.
  36. *
  37. * @param store_type[in] Type of store for the graph. One of the values of
  38. * #LSUP_store_type.
  39. *
  40. * @return LSUP_OK if the graph was created, or < 0 if an error occurred.
  41. */
  42. LSUP_Graph *
  43. LSUP_graph_new_env (
  44. const LSUP_Env *env, LSUP_Term *uri, const LSUP_store_type store_type);
  45. /** @brief Create an empty graph with the default environment.
  46. *
  47. * This is likely to be used more often than #LSUP_graph_new_env().
  48. */
  49. #define LSUP_graph_new(uri, type) \
  50. LSUP_graph_new_env (LSUP_default_env, uri, type)
  51. /** @brief Shortcut for #LSUP_graph_new_lookup_env() on default MDB store.
  52. */
  53. #define LSUP_graph_new_lookup(s, p, o) \
  54. LSUP_graph_new_lookup_env (LSUP_default_env, (s), (p), (o))
  55. /** @brief copy a graph into a new one.
  56. *
  57. * The new graph is compacted to the minimum required size.
  58. *
  59. * src[in] Graph to be copied.
  60. *
  61. * @param uri URI of the destination graph. If NULL, a UUID4 URN is generated.
  62. *
  63. * @param gr[out] Pointer to a pointer to the destination graph. It must be
  64. * freed with #LSUP_graph_free when done.
  65. *
  66. * @return LSUP_OK if the graph was copied, or < 0 if an error occurred.
  67. */
  68. LSUP_Graph *
  69. LSUP_graph_copy (const LSUP_Graph *src);
  70. /** @brief Copy the contents of a graph into a permanent store.
  71. *
  72. * It is possible to store a memory graph, a RAMdisk MDB graph, or a
  73. * permanently stored graph into another environment.
  74. *
  75. * The namespace map associated with the graph is stored into the destination
  76. * as well, except for existing namespaces and prefixes.
  77. *
  78. * @param[in] src Graph to store.
  79. *
  80. * @param[out] dest Pointer to graph handle for the new stored graph. The new
  81. * graph will have the same URI as the source. It may be NULL.
  82. *
  83. * @param[in] env Environment to copy to. If NULL, it is set to the deafult
  84. * LSUP store. This makes it possible to copy MDB graphs across different
  85. * environments. If the source is a MDB graph and the environment is the same
  86. * as the source, no change occurs.
  87. *
  88. * @return LSUP_OK on success; LSUP_NOACTION if the graph is already stored in
  89. * the same enviroment; <0 on error.
  90. */
  91. LSUP_rc
  92. LSUP_graph_store (
  93. const LSUP_Graph *src, LSUP_Graph **dest_p, const LSUP_Env *env);
  94. /** Perform a boolean operation between two graphs.
  95. *
  96. * This method yields a new graph as the result of the operation.
  97. *
  98. * @param op[in] Operation to perform. One of #LSUP_bool_op.
  99. *
  100. * @param gr1[in] First operand.
  101. *
  102. * @param gr2[in] Second operand.
  103. *
  104. * @param res[out] Result graph. It must be freed with #LSUP_graph_free when
  105. * done.
  106. */
  107. LSUP_Graph *
  108. LSUP_graph_bool_op(
  109. const LSUP_bool_op op, const LSUP_Graph *gr1, const LSUP_Graph *gr2);
  110. /** @brief Free a graph.
  111. */
  112. void
  113. LSUP_graph_free (LSUP_Graph *gr);
  114. /** @brief Compare two graphs.
  115. *
  116. * @param[in] gr1 First operand.
  117. *
  118. * @param[in] gr2 Second operand.
  119. *
  120. * @return True if the graphs are topologically equal, false otherwise.
  121. */
  122. bool
  123. LSUP_graph_equals (const LSUP_Graph *gr1, const LSUP_Graph *gr2);
  124. /** @brief Read-only graph URI.
  125. *
  126. * To change the graph URI, use #LSUP_graph_set_uri.
  127. */
  128. LSUP_Term *
  129. LSUP_graph_uri (const LSUP_Graph *gr);
  130. /** Set the URI of a graph.
  131. *
  132. * Note that by changing the URI of a graph backed by a context-sensitive store
  133. * (i.e. LSUP_STORE_MDB*) effectively changes the underlying data set that the
  134. * graph points to. Triples are looked up in, and added to, the context that
  135. * the graph URI represents. A non-context graph retains the same triple set
  136. * when graph URI changes.
  137. *
  138. * @param gr[in] Graph handle.
  139. *
  140. * @param uri[in] IRI handle. The graph takes ownership of the handle.
  141. *
  142. * @return LSUP_OK on success; <0 on error.
  143. */
  144. LSUP_rc
  145. LSUP_graph_set_uri (LSUP_Graph *gr, LSUP_Term *uri);
  146. /** @brief Get the namespace map for an in-memory graph.
  147. *
  148. * @return Namespace handler for in-memory graphs, NULL for MDB graphs.
  149. */
  150. LSUP_NSMap *
  151. LSUP_graph_namespace (const LSUP_Graph *gr);
  152. /** @brief Set the namespace map for an in-memory graph.
  153. *
  154. * This has no effect on MDB graphs.
  155. *
  156. * @param[in] gr Graph to set the namespace map for.
  157. *
  158. * @param[in] nsm Namespace handle.
  159. */
  160. void
  161. LSUP_graph_set_namespace (LSUP_Graph *gr, LSUP_NSMap *nsm);
  162. /** @brief Number of triples in a graph.
  163. */
  164. size_t
  165. LSUP_graph_size (const LSUP_Graph *gr);
  166. /** @brief Whether a graph contains a triple.
  167. *
  168. * @param[in] gr Graph to look up into.
  169. *
  170. * @param[in] spo Triple to look up.
  171. *
  172. * @return 1 if the triple is found, 0 if not found.
  173. */
  174. bool
  175. LSUP_graph_contains (const LSUP_Graph *gr, const LSUP_Triple *spo);
  176. /** @brief Initialize an iterator to add triples.
  177. *
  178. * @param[in] gr Graph to add to. It is added to the iterator state.
  179. *
  180. * @return Iterator handle. This should be passed to #LSUP_graph_add_iter() and
  181. * must be freed with #LSUP_graph_add_done().
  182. */
  183. LSUP_GraphIterator *
  184. LSUP_graph_add_init (LSUP_Graph *gr);
  185. /** @brief Add a single triple to the store.
  186. *
  187. * @param[in] it Iterator obtained with #LSUP_graph_add_init().
  188. *
  189. * @param[in] spo Triple to add. Caller retains ownership.
  190. */
  191. LSUP_rc
  192. LSUP_graph_add_iter (LSUP_GraphIterator *it, const LSUP_Triple *spo);
  193. /** @brief Finalize an add iteration loop and free the iterator.
  194. *
  195. * DO NOT USE with iterators obtained with other than #LSUP_graph_add_init().
  196. *
  197. * @param[in] it Iterator to finalize.
  198. */
  199. void
  200. LSUP_graph_add_done (LSUP_GraphIterator *it);
  201. /** @brief Add triples to a graph.
  202. *
  203. * @param[in] gr Graph to add triples to.
  204. *
  205. * @param[in] trp Array of triples to add. The last triple must be NULL.
  206. *
  207. * @param[in] strp Array of buffer triples to add. The last one must be NULL.
  208. *
  209. * @param[out] inserted This will be filled with the total number of triples
  210. * inserted.
  211. */
  212. LSUP_rc
  213. LSUP_graph_add (LSUP_Graph *gr, const LSUP_Triple trp[], size_t *inserted);
  214. /** @brief Delete triples by a matching pattern.
  215. *
  216. * @param gr[in] Graph to delete triples from.
  217. *
  218. * @param ptn[in] Matching pattern. Any and all of s, p, o can be NULL.
  219. *
  220. * @param ct[out] If not NULL it is populated with the number of triples
  221. * deleted.
  222. */
  223. LSUP_rc
  224. LSUP_graph_remove (
  225. LSUP_Graph *gr, const LSUP_Term *s, const LSUP_Term *p,
  226. const LSUP_Term *o, size_t *ct);
  227. /** @brief Remove a whole graph from a context-aware store.
  228. *
  229. * @param[in] uri Graph (context) to remove.
  230. *
  231. * @return LSUP_OK if the graph was removed; LSUP_NOACTION if no graph was
  232. * found with the given URI; LSUP_VALU_ERR if the graph back end is a non-
  233. * permanent or non-context aware store.
  234. */
  235. /*
  236. LSUP_rc
  237. LSUP_graph_remove_ctx (LSUP_Graph *gr);
  238. */
  239. /** Look up triples by a matching pattern and yield an iterator.
  240. *
  241. * @param gr[in] Graph to look up.
  242. *
  243. * @param spo[in] Triple to look for. Any and all terms can be NULL, which
  244. * indicate unbound terms.
  245. *
  246. * @param it[out] Pointer to a #LSUP_GraphIterator to be generated. It must be
  247. * freed with #LSUP_graph_iter_free after use.
  248. */
  249. LSUP_GraphIterator *
  250. LSUP_graph_lookup (const LSUP_Graph *gr, const LSUP_Term *s,
  251. const LSUP_Term *p, const LSUP_Term *o, size_t *ct);
  252. /** @brief Advance a cursor obtained by a lookup and return a matching triple.
  253. *
  254. * @param it[in] Iterator handle obtained through #LSUP_graph_lookup.
  255. *
  256. * @param spo[out] Triple to be populated with the next result. May be NULL
  257. * (e.g. for counters).
  258. *
  259. * @return LSUP_OK if a result was found; LSUP_END if the end of the match list
  260. * was reached.
  261. */
  262. LSUP_rc
  263. LSUP_graph_iter_next (LSUP_GraphIterator *it, LSUP_Triple *spo);
  264. /** @brief Free a graph iterator.
  265. *
  266. * DO NOT USE with iterators obtained with #LSUP_graph_add_init(). Use
  267. * #LSUP_graph_add_done() with those.
  268. *
  269. * @param[in] it Iterator to finalize.
  270. */
  271. void
  272. LSUP_graph_iter_free (LSUP_GraphIterator *it);
  273. #endif