Mercurial > hg > dav / file diff

--- a/ucx/map.h	Thu Oct 15 12:46:09 2015 +0200
+++ b/ucx/map.h	Thu Oct 15 15:01:50 2015 +0200
@@ -146,22 +146,44 @@
 /**
  * Frees a hash map.
  * 
- * <b>Note:</b> the contents are <b>not</b> freed, use an UcxMempool for that
- * purpose.
+ * <b>Note:</b> the contents are <b>not</b> freed, use ucx_map_free_content()
+ * before calling this function to achieve that.
  * 
  * @param map the map to be freed
+ * @see ucx_map_free_content()
  */
 void ucx_map_free(UcxMap *map);
 
 /**
+ * Frees the contents of a hash map.
+ * 
+ * This is a convenience function that iterates over the map and passes all
+ * values to the specified destructor function (e.g. stdlib free()).
+ * 
+ * You must ensure, that it is valid to pass each value in the map to the same
+ * destructor function.
+ * 
+ * You should free or clear the map afterwards, as the contents will be invalid.
+ * 
+ * @param map for which the contents shall be freed
+ * @param destr pointer to the destructor function
+ * @see ucx_map_free()
+ * @see ucx_map_clear()
+ */
+void ucx_map_free_content(UcxMap *map, ucx_destructor destr);
+
+/**
  * Clears a hash map.
  * 
- * <b>Note:</b> the contents are <b>not</b> freed.
+ * <b>Note:</b> the contents are <b>not</b> freed, use ucx_map_free_content()
+ * before calling this function to achieve that.
  * 
- * @param map the map to be freed
+ * @param map the map to be cleared
+ * @see ucx_map_free_content()
  */
 void ucx_map_clear(UcxMap *map);
 
+
 /**
  * Copies contents from a map to another map using a copy function.
  *