Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/allocator.h.md	Sat Feb 08 14:24:22 2025 +0100
+++ b/docs/Writerside/topics/allocator.h.md	Sat Feb 08 20:38:05 2025 +0100
@@ -107,6 +107,37 @@
 }
 ```
 
+When you are implementing 
+
+## Destructor Functions
+
+The `allocator.h` header also declares two function pointers for destructor functions.
+
+```C
+typedef void (*cx_destructor_func)(void *memory);
+typedef void (*cx_destructor_func2)(void *data, void *memory);
+```
+
+The first one is called _simple_ destructor (e.g. in the context of [collections](collection.h.md)),
+and the second one is called _advanced_ destructor.
+The only difference is that you can pass additional custom `data` to an advanced destructor function.
+
+Destructor functions play a vital role in deep de-allocations.
+Another scenarios, besides destroying elements in a collection, are the de-allocation of objects
+stored in a [memory pool](mempool.h.md) or de-allocations of deeply nested [JSON](json.h.md) objects.
+
+> Destructor functions are not to be confused with `free()`-like functions.
+> The fundamental differences are that 
+> * it is not safe to pass `NULL` to a destructor function
+> * a destructor may only de-allocate the contents inside an object but not the object itself, depending on context
+>
+{style="note"}
+
+> For example, when you are using a [list](list.h.md) that stores elements directly, a destructor function
+> assigned to that collection may only destroy the element's contents but must not deallocate the element's memory.
+> On the other hand, when the list is storing just pointers to the elements, you _may_ want the destructor
+> function to also de-allocate the element's memory when the element is removed from that list.
+
 <seealso>
 <category ref="apidoc">
 <a href="https://ucx.sourceforge.io/api/allocator_8h.html">allocator.h</a>