Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/mempool.h.md	Thu Feb 06 20:26:31 2025 +0100
+++ b/docs/Writerside/topics/mempool.h.md	Fri Feb 07 17:55:28 2025 +0100
@@ -1,21 +1,64 @@
 # Memory Pool
 
-<warning>
-Outdated - Rewrite!
-</warning>
-
 A memory pool is providing an allocator implementation that automatically deallocates the memory upon its destruction.
 It also allows you to register destructor functions for the allocated memory, which are automatically called before
 the memory is deallocated.
-Additionally, you may also register _independent_ destructor functions within a pool in case some external library
-allocated memory for you, which should be freed together with this pool.
+
+Additionally, you may also register _independent_ destructor functions.
+This can be useful, for example, when some library allocates memory that you wish to destroy when the memory pool gets destroyed.
+
+A memory pool can be used with all UCX features that support the use of an [allocator](allocator.h.md).
+For example, the UCX [string](string.h.md) functions provide several variants suffixed with `_a` for that purpose.
+
+## Overview
+
+```C
+CxMempool *cxMempoolCreate(size_t capacity, cx_destructor_func fnc);
+
+CxMempool *cxMempoolCreateSimple(size_t capacity);
+
+void cxMempoolFree(CxMempool *pool);
+
+void cxMempoolSetDestructor(void *memory, cx_destructor_func fnc);
+
+void cxMempoolRemoveDestructor(void *memory);
+
+int cxMempoolRegister(CxMempool *pool, void *memory,
+                      cx_destructor_func fnc);
+```
+
+## Description
 
-Many UCX features support the use of an allocator.
-The [strings](string.h.md), for instance, provide several functions suffixed with `_a` that allow specifying an allocator.
-You can use this to keep track of the memory occupied by dynamically allocated strings and cleanup everything with
-just a single call to `cxMempoolFree()`.
+A memory pool is created with the `cxMempoolCreate()` function with a default `capacity`
+and an optional default destructor function `fnc`.
+If specified, the default destructor function is registered for all freshly allocated memory within the pool,
+as if `cxMempoolSetDestructor()` was called immediately after allocation.
+When you set `fnc` is to `NULL` during pool creation, or use `cxMempoolCreateSimple`, no default destructor is registered.
+
+After creating a memory pool `CxMempool *mpool`, you can access the provided allocator via `mpool->allocator`.
+
+The functions `cxMempoolSetDestructor()` and `cxMempoolRemoveDestructor()` can be used to assign a specific destructor
+function to an allocated object or remove any assigned destructor function, respectively.
+The `memory` pointer points to the allocated object, which must have been allocated by any `CxMempool`'s provided allocator.
 
-The following code illustrates this on the example of reading a CSV file into memory.
+The `cxMempoolRegister()` function allocates a new wrapper object for `memory` with `pool`'s allocator that
+will call the specified destructor function when destroyed.
+Usually this function returns zero except for platforms where memory allocations are likely to fail,
+in which case a non-zero value is returned.
+
+## Order of Destruction
+
+When you call `cxMempoolFree()` the following actions are performed:
+
+1. In any order, for each object in the pool
+   1. the destructor function assigned to that object is called
+   2. the object's memory is deallocated
+2. The pool memory is deallocated
+3. The pool structure is deallocated
+
+## Example
+
+The following code illustrates how the contents of a CSV file are read into pooled memory.
 ```C
 #include <stdio.h>
 #include <cx/mempool.h>
@@ -31,10 +74,11 @@
 } CSVData;
 
 int main(void) {
-    CxMempool* pool = cxBasicMempoolCreate(128);
+    // create a simple pool for various different objects
+    CxMempool* pool = cxMempoolCreateSimple(128);
 
     FILE *f = fopen("test.csv", "r");
-    if (!f) {
+    if (f == NULL) {
         perror("Cannot open file");
         return 1;
     }
@@ -42,25 +86,33 @@
     cxMempoolRegister(pool, f, (cx_destructor_func) fclose);
 
     // create a buffer using the memory pool for destruction
-    CxBuffer *content = cxBufferCreate(NULL, 256, pool->allocator, CX_BUFFER_AUTO_EXTEND);
+    CxBuffer *content = cxBufferCreate(
+            NULL, 256, pool->allocator, CX_BUFFER_AUTO_EXTEND
+    );
 
     // read the file into the buffer and turn it into a string
-    cx_stream_copy(f, content, (cx_read_func) fread, cxBufferWriteFunc);
+    cx_stream_copy(
+        f, content, (cx_read_func) fread, cxBufferWriteFunc
+    );
     fclose(f);
     cxstring contentstr = cx_strn(content->space, content->size);
 
-    // split the string into lines - use the mempool for allocating the target array
+    // split the string into lines
+    // use the memory pool to allocate the target array
     cxstring* lines;
-    size_t lc = cx_strsplit_a(pool->allocator, contentstr,
-                              CX_STR("\n"), SIZE_MAX, &lines);
+    size_t lc = cx_strsplit_a(
+        pool->allocator, contentstr, cx_str("\n"), SIZE_MAX, &lines
+    );
 
     // skip the header and parse the remaining data into a linked list
-    // the nodes of the linked list shall also be allocated by the mempool
-    CxList* datalist = cxLinkedListCreate(pool->allocator, NULL, sizeof(CSVData));
+    // the nodes of the list shall also be allocated by the pool
+    CxList* datalist = cxLinkedListCreate(
+        pool->allocator, NULL, sizeof(CSVData)
+    );
     for (size_t i = 1 ; i < lc ; i++) {
         if (lines[i].length == 0) continue;
         cxstring fields[3];
-        size_t fc = cx_strsplit(lines[i], CX_STR(";"), 3, fields);
+        size_t fc = cx_strsplit(lines[i], cx_str(";"), 3, fields);
         if (fc != 3) {
             fprintf(stderr, "Syntax error in line %zu.\n", i);
             cxMempoolFree(pool);
@@ -92,9 +144,8 @@
 } 
 ```
 
-## Undocumented Symbols (TODO)
-### cxMempoolCreate
-### cxMempoolFree
-### cxMempoolRegister
-### cxMempoolRemoveDestructor
-### cxMempoolSetDestructor
+<seealso>
+<category ref="apidoc">
+<a href="https://ucx.sourceforge.io/api/mempool_8h.html">mempool.h</a>
+</category>
+</seealso>