ucx: comparison docs/src/modules.md

-:0f83916c1639
+:8628147734d6
 Here we have a concrete allocator implementation in the sense of a memory pool.
 This pool allows you to register destructor functions for the allocated memory,
 which are automatically called on the destruction of the pool.
 But you may also register *independent* destructor functions within a pool in
-case, some external library allocated memory for you, which you wish to be
+case some external library allocated memory for you, which should be
 destroyed together with this pool.
+Many UCX modules support the use of an allocator.
+The [String Module](#string), for instance, provides the `sstrdup_a()` function,
+which uses the specified allocator to allocate the memory for the duplicated
+string.
+This way, you can use a `UcxMempool` to keep track of the memory occupied by
+duplicated strings and cleanup everything with just a single call to
+`ucx_mempool_destroy()`.
+### Read CSV data into a structure
+The following code example shows some of the basic memory pool functions and
+how they can be used with other UCX modules.
+```C
+#include <stdio.h>
+#include <ucx/mempool.h>
+#include <ucx/list.h>
+#include <ucx/string.h>
+#include <ucx/buffer.h>
+#include <ucx/utils.h>
+typedef struct {
+sstr_t column_a;
+sstr_t column_b;
+sstr_t column_c;
+} CSVData;
+int main(int argc, char** argv) {
+UcxMempool* pool = ucx_mempool_new(128);
+FILE *f = fopen("test.csv", "r");
+if (!f) {
+perror("Cannot open file");
+return 1;
+}
+/* close the file automatically at pool destruction*/
+ucx_mempool_reg_destr(pool, f, (ucx_destructor) fclose);
+/* create a buffer and register it at the memory pool for destruction */
+UcxBuffer* content = ucx_buffer_new(NULL, 256, UCX_BUFFER_AUTOEXTEND);
+ucx_mempool_reg_destr(pool, content, (ucx_destructor) ucx_buffer_free);
+/* read the file and split it by lines first */
+ucx_stream_copy(f, content, fread, ucx_buffer_write);
+sstr_t contentstr = ucx_buffer_to_sstr(content);
+ssize_t lc = 0;
+sstr_t* lines = sstrsplit_a(pool->allocator, contentstr, S("\n"), &lc);
+/* skip the header and parse the remaining data */
+UcxList* datalist = NULL;
+for (size_t i = 1 ; i < lc ; i++) {
+if (lines[i].length == 0) continue;
+ssize_t fc = 3;
+sstr_t* fields = sstrsplit_a(pool->allocator, lines[i], S(";"), &fc);
+if (fc != 3) {
+fprintf(stderr, "Syntax error in line %zu.\n", i);
+ucx_mempool_destroy(pool);
+return 1;
+}
+CSVData* data = ucx_mempool_malloc(pool, sizeof(CSVData));
+data->column_a = fields[0];
+data->column_b = fields[1];
+data->column_c = fields[2];
+datalist = ucx_list_append_a(pool->allocator, datalist, data);
+}
+/* control output */
+UCX_FOREACH(elem, datalist) {
+CSVData* data = elem->data;
+printf("Column A: %" PRIsstr " | "
+"Column B: %" PRIsstr " | "
+"Column C: %" PRIsstr "\n",
+SFMT(data->column_a), SFMT(data->column_b), SFMT(data->column_c)
+);
+}
+/* cleanup everything, no manual free() needed */
+ucx_mempool_destroy(pool);
+return 0;
+}
+```
+### Overriding the default destructor
+Sometimes you need to allocate memory with `ucx_mempool_malloc()`, but the
+memory is not supposed to be freed with a simple call to `free()`.
+In this case, you can overwrite the default destructor as follows:
+```C
+MyObject* obj = ucx_mempool_malloc(pool, sizeof(MyObject));
+/* some special initialization with own resource management */
+my_object_init(obj);
+/* register destructor function */
+ucx_mempool_set_destr(obj, (ucx_destructor) my_object_destroy);
+```
+But aware, that your destructor function should not free any memory, that is
+also managed by the pool.
+Otherwise you might be risking a double-free.
 ## Properties
 *Header file:* [properties.h](api/properties_8h.html)
 *Required modules:* [Map](#map)

Mercurial > hg > ucx / file comparison

comparison: docs/src/modules.md

docs/src/modules.md