# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1527671632 -7200
# Node ID 3dd7d21fb76bf544dfcfc22e7432d70764f220b9
# Parent  a3e63cb21e204d60bacae1aca5c3b6dafaf794c1
being more precise on the different required behavior of a destructor function for pooled and non-pooled memory

diff -r a3e63cb21e20 -r 3dd7d21fb76b docs/src/modules.md
--- a/docs/src/modules.md	Tue May 29 11:05:12 2018 +0200
+++ b/docs/src/modules.md	Wed May 30 11:13:52 2018 +0200
@@ -455,6 +455,10 @@
 Be 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.
+More precisely, a destructor function set with `ucx_mempool_set_destr()` MUST
+NOT call `free()` on the specified pointer whereas a desructor function
+registered with `ucx_mempool_reg_destr()` MAY (and in most cases will) call
+`free()`.
 
 ## Properties
 
diff -r a3e63cb21e20 -r 3dd7d21fb76b src/ucx/mempool.h
--- a/src/ucx/mempool.h	Tue May 29 11:05:12 2018 +0200
+++ b/src/ucx/mempool.h	Wed May 30 11:13:52 2018 +0200
@@ -164,6 +164,9 @@
  * 
  * The destructor is automatically called when the memory is freed or the
  * pool is destroyed.
+ * A destructor for pooled memory <b>MUST NOT</b> free the memory itself,
+ * as this is done by the pool. Use a destructor to free any resources
+ * managed by the pooled object.
  * 
  * The only requirement for the specified memory is, that it <b>MUST</b> be
  * pooled memory by a UcxMempool or an element-compatible mempool. The pointer
@@ -179,12 +182,18 @@
 
 /**
  * Registers a destructor function for the specified (non-pooled) memory.
- * 
+ *
  * This is useful, if you have memory that has not been allocated by a mempool,
  * but shall be managed by a mempool.
  * 
  * This function creates an entry in the specified mempool and the memory will
  * therefore (logically) convert to pooled memory.
+ * <b>However, this does not cause the memory to be freed automatically!</b>.
+ * If you want to use this function, make the memory pool free non-pooled
+ * memory, the specified destructor function must call <code>free()</code>
+ * by itself. But keep in mind, that you then MUST NOT use this destructor
+ * function with pooled memory (e.g. in ucx_mempool_set_destr()), as it
+ * would cause a double-free.
  * 
  * @param pool the memory pool
  * @param ptr data the destructor is registered for