Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/mempool.h.md	Fri Apr 11 09:15:21 2025 +0200
+++ b/docs/Writerside/topics/mempool.h.md	Fri Apr 11 13:20:07 2025 +0200
@@ -10,7 +10,7 @@
 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
+## Basic Memory Management
 
 ```C
 #include <cx/mempool.h>
@@ -29,8 +29,6 @@
                       cx_destructor_func fnc);
 ```
 
-## Description
-
 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,
@@ -48,7 +46,7 @@
 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
+### Order of Destruction
 
 When you call `cxMempoolFree()` the following actions are performed:
 
@@ -58,6 +56,34 @@
 2. The pool memory is deallocated
 3. The pool structure is deallocated
 
+## Transfer Memory
+
+```C
+#include <cx/mempool.h>
+
+int cxMempoolTransfer(CxMempool *source, CxMempool *dest);
+```
+
+Memory managed by a pool can be transferred to another pool.
+
+The function `cxMempoolTransfer()` transfers all memory managed and/or registered with the `source` pool to the `dest` pool.
+It also registers its allocator with the `dest` pool and creates a new allocator for the `source` pool.
+That means, that all references to the allocator of the `source` pool remain valid and continue to work with the `dest` pool.
+The transferred allocator will be destroyed when the `dest` pool gets destroyed.
+
+The function returns zero when the transfer was successful and non-zero if a necessary memory allocation was not possible,
+or the `source` and `dest` pointers point to the same pool.
+In case of an error, no memory is transferred and both pools are in a valid state.
+
+> Although the allocator from the `source` pool remains valid for the already allocated objects,
+> it is **not** valid to use that allocator to allocate new objects in the `dest` pool.
+> It may only be used to free or reallocate the memory of the existing objects.
+> 
+> The reason is, that the allocator will be destroyed after destroying all objects from the `source` pool and
+> _before_ destroying objects in the `dest` pool which were allocated after the transfer.
+>{style="warning"}
+
+
 ## Example
 
 The following code illustrates how the contents of a CSV file are read into pooled memory.