diff -r 11f3bb408051 -r 62921b370c60 ucx/mempool.h
--- a/ucx/mempool.h Wed Nov 22 12:59:13 2017 +0100
+++ b/ucx/mempool.h Sun Jan 21 12:13:09 2018 +0100
@@ -1,7 +1,7 @@
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
- * Copyright 2015 Olaf Wintermann. All rights reserved.
+ * Copyright 2016 Olaf Wintermann. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
@@ -70,39 +70,29 @@
/**
* Creates a memory pool with the specified initial size.
*
- * As the created memory pool automatically grows in size by 16 elements, when
+ * As the created memory pool automatically grows in size by factor two when
* trying to allocate memory on a full pool, it is recommended that you use
- * a multiple of 16 for the initial size.
+ * a power of two for the initial size.
*
- * @param n initial pool size (should be a multiple of 16)
+ * @param n initial pool size (should be a power of two, e.g. 16)
* @return a pointer to the new memory pool
+ * @see ucx_mempool_new_default()
*/
UcxMempool *ucx_mempool_new(size_t n);
/**
* Resizes a memory pool.
*
+ * This function will fail if the new capacity is not sufficient for the
+ * present data.
+ *
* @param pool the pool to resize
* @param newcap the new capacity
- * @return EXIT_SUCCESS
on success or
- * EXIT_FAILURE
on failure
+ * @return zero on success or non-zero on failure
*/
int ucx_mempool_chcap(UcxMempool *pool, size_t newcap);
/**
- * Changes the pool size to the next smallest multiple of 16.
- *
- * You may use this macro, to reduce the pool size after freeing
- * many pooled memory items.
- *
- * @param pool the pool to clamp
- * @return EXIT_SUCCESS
on success or
- * EXIT_FAILURE
on failure
- */
-#define ucx_mempool_clamp(pool) ucx_mempool_chcap(pool, \
- (pool->ndata & ~0xF)+0x10)
-
-/**
* Allocates pooled memory.
*
* @param pool the memory pool
@@ -127,10 +117,8 @@
/**
* Reallocates pooled memory.
*
- * If the memory to be reallocated is not contained by the specified pool, this
- * function will possibly fail. In case the memory had to be moved to another
- * location, this function will print out a message to stderr
- * and exit the program with error code EXIT_FAILURE
.
+ * If the memory to be reallocated is not contained by the specified pool, the
+ * behavior is undefined.
*
* @param pool the memory pool
* @param ptr a pointer to the memory that shall be reallocated
@@ -146,10 +134,8 @@
* Before freeing the memory, the specified destructor function (if any)
* is called.
*
- * If you specify memory, that is not pooled by the specified memory pool, this
- * is considered as a severe error and an error message is written to
- * stderr
and the application is shut down with code
- * EXIT_FAILURE
.
+ * If you specify memory, that is not pooled by the specified memory pool, the
+ * program will terminate with a call to abort()
.
*
* @param pool the memory pool
* @param ptr a pointer to the memory that shall be freed
@@ -180,7 +166,7 @@
* pool is destroyed.
*
* The only requirement for the specified memory is, that it MUST be
- * pooled memory by an UcxMempool or an element-compatible mempool. The pointer
+ * pooled memory by a UcxMempool or an element-compatible mempool. The pointer
* to the destructor function is saved in a reserved area before the actual
* memory.
*