buffer.h 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254
  1. #ifndef _LSUP_BUFFER_H
  2. #define _LSUP_BUFFER_H
  3. #include "core.h"
  4. // "NULL" key, a value that is never user-provided. Used to mark special
  5. // values (e.g. deleted records).
  6. #define NULL_KEY 0
  7. /** @brief General-purpose data buffer.
  8. *
  9. * The structure is transparently exposed so that the related API only defines
  10. * few basic helper methods. Other operations, such as appending, may be
  11. * performed by simply using the addr and size attributes.
  12. *
  13. * A buffer can be initialized once and reused multiple times, e.g. in a loop,
  14. * without being freed between iterations, by using #LSUP_buffer_init.
  15. */
  16. typedef struct LSUP_Buffer {
  17. /*@null@*/ void *addr;
  18. size_t size;
  19. } LSUP_Buffer;
  20. /** @brief Triple of byte buffers.
  21. *
  22. * This is a generic data triple. Store implementations should handle this
  23. * data type rather than RDF terms and triples. Conversion to/from RDF terms
  24. * and triples is done in the term and triple modules.
  25. */
  26. typedef struct buffer_triple_t {
  27. LSUP_Buffer *s;
  28. LSUP_Buffer *p;
  29. LSUP_Buffer *o;
  30. } LSUP_BufferTriple;
  31. typedef enum {
  32. TRP_POS_S = 0,
  33. TRP_POS_P = 1,
  34. TRP_POS_O = 2,
  35. } LSUP_TriplePos;
  36. /** Initialize or reuse a buffer handle.
  37. *
  38. * The handle must have been created with #LSUP_buffer_new*().
  39. *
  40. * The data block is resized without being freed first. The handle must be
  41. * eventually freed with #LSUP_buffer_done() after use.
  42. *
  43. * @param buf[in] A buffer handle obtained with #LSUP_buffer_new or by manual
  44. * allocation.
  45. *
  46. * @param size[in] New size.
  47. *
  48. * @param data[in] If not NULL, data to replace the existing ones. The size
  49. * of the data to be copied is determined by the size parameter. If NULL, the
  50. * existing data are preserved as with a normal realloc().
  51. */
  52. LSUP_rc
  53. LSUP_buffer_init (LSUP_Buffer *buf, const size_t size, const void *data);
  54. /** @brief Create a new buffer and optionally populate it with data.
  55. *
  56. * To change the buffer size and/or data later call #LSUP_buffer_init.
  57. *
  58. * To copy a buffer just do buf2 = LSUP_buffer_new (buf1->size, buf1->addr);
  59. *
  60. * @param size[in] Length of the data.
  61. *
  62. * @param data[in] Optional data to initially populate the object with. If
  63. * NULL, the buffer data are garbage.
  64. *
  65. * @return LSUP_Buffer pointer. It must be freed with #LSUP_buffer_free. NULL
  66. * on error.
  67. */
  68. inline LSUP_Buffer *
  69. LSUP_buffer_new (const size_t size, const void *data)
  70. {
  71. LSUP_Buffer *buf;
  72. CALLOC_GUARD (buf, NULL);
  73. if (LSUP_buffer_init (buf, size, data) != LSUP_OK) {
  74. free (buf->addr);
  75. free (buf);
  76. return NULL;
  77. }
  78. return buf;
  79. }
  80. /** @brief Dummy buffer to be used with #LSUP_buffer_init.
  81. */
  82. #define BUF_DUMMY LSUP_buffer_new (0, NULL)
  83. /** @brief Free the content of a buffer.
  84. */
  85. void LSUP_buffer_done (LSUP_Buffer *buf);
  86. /** @brief Free a buffer.
  87. */
  88. void LSUP_buffer_free (LSUP_Buffer *buf);
  89. /** @brief Hash a buffer.
  90. */
  91. inline LSUP_Key
  92. LSUP_buffer_hash (const LSUP_Buffer *buf)
  93. {
  94. return (buf == NULL) ? NULL_KEY :
  95. LSUP_HASH (buf->addr, buf->size, LSUP_HASH_SEED);
  96. }
  97. /** @brief Print a byte string of a given length in a human-readable format.
  98. *
  99. * The string is printed in Python style: printable characters are output
  100. * literally, and non-printable ones as hex sequences.
  101. */
  102. void LSUP_buffer_print (const LSUP_Buffer *buf);
  103. /** @brief Format a buffer into anb ASCII string.
  104. *
  105. * The string has non-printable characters escaped as "\xNN".
  106. *
  107. * @param buf[in] Buffer to convert.
  108. *
  109. * @return Formatted string. It must be freed with free().
  110. */
  111. char *
  112. LSUP_buffer_as_str (const LSUP_Buffer *buf);
  113. /** @brief Compare two buffers.
  114. *
  115. * The return value is the same as memcmp.
  116. */
  117. inline int LSUP_buffer_cmp (const LSUP_Buffer *buf1, const LSUP_Buffer *buf2)
  118. {
  119. return memcmp (
  120. buf1->addr, buf2->addr,
  121. (buf1->size > buf2->size ? buf1->size : buf2->size));
  122. }
  123. /** @brief Return whether two buffers are equal.
  124. *
  125. * This may be faster than #LSUP_buffer_cmp() because it does a size comparison
  126. * first.
  127. */
  128. inline bool LSUP_buffer_eq (const LSUP_Buffer *buf1, const LSUP_Buffer *buf2)
  129. {
  130. if (buf1->size != buf2->size) return false;
  131. return (LSUP_buffer_cmp (buf1, buf2) == 0) ? true : false;
  132. }
  133. /*
  134. * Buffer triples.
  135. */
  136. LSUP_BufferTriple *
  137. LSUP_btriple_new(LSUP_Buffer *s, LSUP_Buffer *p, LSUP_Buffer *o);
  138. /** @brief Initialize internal term pointers in a heap-allocated buffer triple.
  139. *
  140. * The triple must be freed with #LSUP_btriple_free().
  141. *
  142. * @param sspo[in] Serialized triple pointer to initialize.
  143. */
  144. LSUP_rc
  145. LSUP_btriple_init (
  146. LSUP_BufferTriple *sspo,
  147. LSUP_Buffer *s, LSUP_Buffer *p, LSUP_Buffer *o);
  148. /** @brief Free the internal pointers of a buffer triple.
  149. *
  150. * @param sspo[in] Buffer triple to be freed.
  151. */
  152. void
  153. LSUP_btriple_done (LSUP_BufferTriple *sspo);
  154. /** @brief Free a buffer triple and all its internal pointers.
  155. *
  156. * NOTE: If the buffer pointers are not to be freed (e.g. they are owned by a
  157. * back end), use a simple free(sspo) instead of this.
  158. *
  159. * @param sspo[in] Buffer triple to be freed.
  160. */
  161. void
  162. LSUP_btriple_free (LSUP_BufferTriple *sspo);
  163. /** @brief Free a buffer triple and its buffer handles but not the buffer data.
  164. *
  165. * This is useful when freeing a "dummy" triple whose buffers are owned by the
  166. * caller but the data the terms point to are owned by the store.
  167. *
  168. */
  169. void
  170. LSUP_btriple_free_shallow (LSUP_BufferTriple *sspo);
  171. /** @brief Get serialized triple by term position.
  172. *
  173. * Useful for looping over all terms.
  174. *
  175. * @param trp[in] Serialized triple pointer.
  176. *
  177. * @param n[in] A number between 0÷2.
  178. *
  179. * @return Corresponding serialized term or NULL if n is out of range.
  180. */
  181. inline LSUP_Buffer *
  182. LSUP_btriple_pos (const LSUP_BufferTriple *btrp, LSUP_TriplePos n)
  183. {
  184. if (n == TRP_POS_S) return btrp->s;
  185. if (n == TRP_POS_P) return btrp->p;
  186. if (n == TRP_POS_O) return btrp->o;
  187. return NULL;
  188. }
  189. /** @brief Hash a buffer triple.
  190. *
  191. * TODO This doesn't handle blank nodes correctly.
  192. */
  193. inline LSUP_Key
  194. LSUP_btriple_hash (const LSUP_BufferTriple *strp)
  195. {
  196. return LSUP_HASH (
  197. strp->s->addr, strp->s->size,
  198. LSUP_HASH (
  199. strp->p->addr, strp->p->size,
  200. LSUP_HASH (strp->o->addr, strp->o->size, LSUP_HASH_SEED)
  201. )
  202. );
  203. }
  204. #define STRP_DUMMY LSUP_btriple_new (NULL, NULL, NULL)
  205. #endif