toolkit: comparison ucx/cx/allocator.h

-:bf7084544cb1
+:7c4b9cba09ca
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
 /**
-* \file allocator.h
+* @file allocator.h
 * Interface for custom allocators.
 */
 #ifndef UCX_ALLOCATOR_H
 #define UCX_ALLOCATOR_H
 );
 /**
 * The allocator's realloc() implementation.
 */
-__attribute__((__warn_unused_result__))
 void *(*realloc)(
 void *data,
 void *mem,
 size_t n
 );
 );
 /**
 * The allocator's free() implementation.
 */
-__attribute__((__nonnull__))
 void (*free)(
 void *data,
 void *mem
 );
 } cx_allocator_class;
 /**
 * Function pointer type for destructor functions.
 *
 * A destructor function deallocates possible contents and MAY free the memory
-* pointed to by \p memory. Read the documentation of the respective function
+* pointed to by @p memory. Read the documentation of the respective function
-* pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
+* pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
-* particular implementation.
+* that particular implementation.
 *
 * @param memory a pointer to the object to destruct
 */
-__attribute__((__nonnull__))
 typedef void (*cx_destructor_func)(void *memory);
 /**
 * Function pointer type for destructor functions.
 *
 * A destructor function deallocates possible contents and MAY free the memory
-* pointed to by \p memory. Read the documentation of the respective function
+* pointed to by @p memory. Read the documentation of the respective function
-* pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
+* pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
-* particular implementation.
+* that particular implementation.
 *
 * @param data an optional pointer to custom data
 * @param memory a pointer to the object to destruct
 */
-__attribute__((__nonnull__(2)))
 typedef void (*cx_destructor_func2)(
 void *data,
 void *memory
 );
 /**
-* Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
+* Re-allocate a previously allocated block and changes the pointer in-place,
-*
+* if necessary.
-* \par Error handling
+*
-* \c errno will be set by realloc() on failure.
+* @par Error handling
+* @c errno will be set by realloc() on failure.
 *
 * @param mem pointer to the pointer to allocated block
 * @param n the new size in bytes
-* @return zero on success, non-zero on failure
+* @retval zero success
-*/
+* @retval non-zero failure
-__attribute__((__nonnull__))
+* @see cx_reallocatearray()
+*/
+cx_attr_nonnull
+cx_attr_nodiscard
 int cx_reallocate(
 void **mem,
 size_t n
 );
 /**
-* Allocate \p n bytes of memory.
+* Re-allocate a previously allocated block and changes the pointer in-place,
+* if necessary.
+*
+* The size is calculated by multiplying @p nemb and @p size.
+*
+* @par Error handling
+* @c errno will be set by realloc() on failure or when the multiplication of
+* @p nmemb and @p size overflows.
+*
+* @param mem pointer to the pointer to allocated block
+* @param nmemb the number of elements
+* @param size the size of each element
+* @retval zero success
+* @retval non-zero failure
+* @see cx_reallocate()
+*/
+cx_attr_nonnull
+cx_attr_nodiscard
+int cx_reallocatearray(
+void **mem,
+size_t nmemb,
+size_t size
+);
+/**
+* Re-allocate a previously allocated block and changes the pointer in-place,
+* if necessary.
+*
+* @par Error handling
+* @c errno will be set by realloc() on failure.
+*
+* @param mem (@c void**) pointer to the pointer to allocated block
+* @param n (@c size_t) the new size in bytes
+* @retval zero success
+* @retval non-zero failure
+* @see cx_reallocatearray()
+*/
+#define cx_reallocate(mem, n) cx_reallocate((void**)(mem), n)
+/**
+* Re-allocate a previously allocated block and changes the pointer in-place,
+* if necessary.
+*
+* The size is calculated by multiplying @p nemb and @p size.
+*
+* @par Error handling
+* @c errno will be set by realloc() on failure or when the multiplication of
+* @p nmemb and @p size overflows.
+*
+* @param mem (@c void**) pointer to the pointer to allocated block
+* @param nmemb (@c size_t) the number of elements
+* @param size (@c size_t) the size of each element
+* @retval zero success
+* @retval non-zero failure
+*/
+#define cx_reallocatearray(mem, nmemb, size) \
+cx_reallocatearray((void**)(mem), nmemb, size)
+/**
+* Free a block allocated by this allocator.
+*
+* @note Freeing a block of a different allocator is undefined.
+*
+* @param allocator the allocator
+* @param mem a pointer to the block to free
+*/
+cx_attr_nonnull_arg(1)
+void cxFree(
+const CxAllocator *allocator,
+void *mem
+);
+/**
+* Allocate @p n bytes of memory.
 *
 * @param allocator the allocator
 * @param n the number of bytes
 * @return a pointer to the allocated memory
 */
-__attribute__((__malloc__))
+cx_attr_nodiscard
-__attribute__((__alloc_size__(2)))
+cx_attr_nonnull
+cx_attr_malloc
+cx_attr_dealloc_ucx
+cx_attr_allocsize(2)
 void *cxMalloc(
 const CxAllocator *allocator,
 size_t n
 );
 /**
-* Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
+* Re-allocate the previously allocated block in @p mem, making the new block
-* This function may return the same pointer that was passed to it, if moving the memory
+* @p n bytes long.
-* was not necessary.
+* This function may return the same pointer that was passed to it, if moving
-*
+* the memory was not necessary.
-* \note Re-allocating a block allocated by a different allocator is undefined.
+*
+* @note Re-allocating a block allocated by a different allocator is undefined.
 *
 * @param allocator the allocator
 * @param mem pointer to the previously allocated block
 * @param n the new size in bytes
 * @return a pointer to the re-allocated memory
 */
-__attribute__((__warn_unused_result__))
+cx_attr_nodiscard
-__attribute__((__alloc_size__(3)))
+cx_attr_nonnull_arg(1)
+cx_attr_dealloc_ucx
+cx_attr_allocsize(3)
 void *cxRealloc(
 const CxAllocator *allocator,
 void *mem,
 size_t n
 );
 /**
-* Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
+* Re-allocate the previously allocated block in @p mem, making the new block
-* This function acts like cxRealloc() using the pointer pointed to by \p mem.
+* @p n bytes long.
-*
+* This function may return the same pointer that was passed to it, if moving
-* \note Re-allocating a block allocated by a different allocator is undefined.
+* the memory was not necessary.
 *
-* \par Error handling
+* The size is calculated by multiplying @p nemb and @p size.
-* \c errno will be set, if the underlying realloc function does so.
+* If that multiplication overflows, this function returns @c NULL and @c errno
+* will be set.
+*
+* @note Re-allocating a block allocated by a different allocator is undefined.
+*
+* @param allocator the allocator
+* @param mem pointer to the previously allocated block
+* @param nmemb the number of elements
+* @param size the size of each element
+* @return a pointer to the re-allocated memory
+*/
+cx_attr_nodiscard
+cx_attr_nonnull_arg(1)
+cx_attr_dealloc_ucx
+cx_attr_allocsize(3, 4)
+void *cxReallocArray(
+const CxAllocator *allocator,
+void *mem,
+size_t nmemb,
+size_t size
+);
+/**
+* Re-allocate a previously allocated block and changes the pointer in-place,
+* if necessary.
+* This function acts like cxRealloc() using the pointer pointed to by @p mem.
+*
+* @note Re-allocating a block allocated by a different allocator is undefined.
+*
+* @par Error handling
+* @c errno will be set, if the underlying realloc function does so.
 *
 * @param allocator the allocator
 * @param mem pointer to the pointer to allocated block
 * @param n the new size in bytes
-* @return zero on success, non-zero on failure
+* @retval zero success
-*/
+* @retval non-zero failure
-__attribute__((__nonnull__))
+*/
+cx_attr_nodiscard
+cx_attr_nonnull
 int cxReallocate(
 const CxAllocator *allocator,
 void **mem,
 size_t n
 );
 /**
-* Allocate \p nelem elements of \p n bytes each, all initialized to zero.
+* Re-allocate a previously allocated block and changes the pointer in-place,
+* if necessary.
+* This function acts like cxRealloc() using the pointer pointed to by @p mem.
+*
+* @note Re-allocating a block allocated by a different allocator is undefined.
+*
+* @par Error handling
+* @c errno will be set, if the underlying realloc function does so.
+*
+* @param allocator (@c CxAllocator*) the allocator
+* @param mem (@c void**) pointer to the pointer to allocated block
+* @param n (@c size_t) the new size in bytes
+* @retval zero success
+* @retval non-zero failure
+*/
+#define cxReallocate(allocator, mem, n) \
+cxReallocate(allocator, (void**)(mem), n)
+/**
+* Re-allocate a previously allocated block and changes the pointer in-place,
+* if necessary.
+* This function acts like cxReallocArray() using the pointer pointed to
+* by @p mem.
+*
+* @note Re-allocating a block allocated by a different allocator is undefined.
+*
+* @par Error handling
+* @c errno will be set, if the underlying realloc function does so or the
+* multiplication of @p nmemb and @p size overflows.
+*
+* @param allocator the allocator
+* @param mem pointer to the pointer to allocated block
+* @param nmemb the number of elements
+* @param size the size of each element
+* @retval zero success
+* @retval non-zero on failure
+*/
+cx_attr_nodiscard
+cx_attr_nonnull
+int cxReallocateArray(
+const CxAllocator *allocator,
+void **mem,
+size_t nmemb,
+size_t size
+);
+/**
+* Re-allocate a previously allocated block and changes the pointer in-place,
+* if necessary.
+* This function acts like cxReallocArray() using the pointer pointed to
+* by @p mem.
+*
+* @note Re-allocating a block allocated by a different allocator is undefined.
+*
+* @par Error handling
+* @c errno will be set, if the underlying realloc function does so or the
+* multiplication of @p nmemb and @p size overflows.
+*
+* @param allocator (@c CxAllocator*) the allocator
+* @param mem (@c void**) pointer to the pointer to allocated block
+* @param nmemb (@c size_t) the number of elements
+* @param size (@c size_t) the size of each element
+* @retval zero success
+* @retval non-zero failure
+*/
+#define cxReallocateArray(allocator, mem, nmemb, size) \
+cxReallocateArray(allocator, (void**) (mem), nmemb, size)
+/**
+* Allocate @p nelem elements of @p n bytes each, all initialized to zero.
 *
 * @param allocator the allocator
 * @param nelem the number of elements
 * @param n the size of each element in bytes
 * @return a pointer to the allocated memory
 */
-__attribute__((__malloc__))
+cx_attr_nonnull_arg(1)
-__attribute__((__alloc_size__(2, 3)))
+cx_attr_nodiscard
+cx_attr_malloc
+cx_attr_dealloc_ucx
+cx_attr_allocsize(2, 3)
 void *cxCalloc(
 const CxAllocator *allocator,
 size_t nelem,
 size_t n
-);
-/**
-* Free a block allocated by this allocator.
-*
-* \note Freeing a block of a different allocator is undefined.
-*
-* @param allocator the allocator
-* @param mem a pointer to the block to free
-*/
-__attribute__((__nonnull__))
-void cxFree(
-const CxAllocator *allocator,
-void *mem
 );
 #ifdef __cplusplus
 } // extern "C"
 #endif

Mercurial > hg > toolkit / file comparison

comparison: ucx/cx/allocator.h

ucx/cx/allocator.h