1.1 --- a/src/ucx/stack.h Sat May 12 14:56:17 2018 +0200
1.2 +++ b/src/ucx/stack.h Sun May 13 17:34:06 2018 +0200
1.3 @@ -91,19 +91,23 @@
1.4 *
1.5 * @param stack a pointer to the stack
1.6 * @param n amount of memory to allocate
1.7 - * @return a pointer to the allocated memory
1.8 + * @return a pointer to the allocated memory or <code>NULL</code> on stack
1.9 + * overflow
1.10 * @see ucx_allocator_malloc()
1.11 */
1.12 void *ucx_stack_malloc(UcxStack *stack, size_t n);
1.13
1.14 /**
1.15 - * Alias for #ucx_stack_malloc().
1.16 + * Allocates memory with #ucx_stack_malloc() and copies the specified data if
1.17 + * the allocation was successful.
1.18 + *
1.19 * @param stack a pointer to the stack
1.20 * @param n amount of memory to allocate
1.21 + * @param data a pointer to the data to copy
1.22 * @return a pointer to the allocated memory
1.23 * @see ucx_stack_malloc
1.24 */
1.25 -#define ucx_stack_push(stack, n) ucx_stack_malloc(stack, n)
1.26 +void *ucx_stack_push(UcxStack *stack, size_t n, const void *data);
1.27
1.28 /**
1.29 * Allocates an array of stack memory
1.30 @@ -119,15 +123,18 @@
1.31 void *ucx_stack_calloc(UcxStack *stack, size_t nelem, size_t elsize);
1.32
1.33 /**
1.34 - * Alias for #ucx_stack_calloc().
1.35 + * Allocates memory with #ucx_stack_calloc() and copies the specified data if
1.36 + * the allocation was successful.
1.37 *
1.38 * @param stack a pointer to the stack
1.39 - * @param n amount of elements to allocate
1.40 + * @param nelem amount of elements to allocate
1.41 * @param elsize amount of memory per element
1.42 + * @param data a pointer to the data
1.43 * @return a pointer to the allocated memory
1.44 * @see ucx_stack_calloc
1.45 */
1.46 -#define ucx_stack_pusharr(stack,n,elsize) ucx_stack_calloc(stack,n,elssize)
1.47 +void *ucx_stack_pusharr(UcxStack *stack,
1.48 + size_t nelem, size_t elsize, const void *data);
1.49
1.50 /**
1.51 * Reallocates memory on the stack.
1.52 @@ -184,12 +191,13 @@
1.53 * Removes the top most element from the stack and copies the content to <code>
1.54 * dest</code>.
1.55 *
1.56 - * In contrast to #ucx_stack_pop() the <code>dest</code> pointer <code>MUST
1.57 - * NOT</code> be <code>NULL</code>.
1.58 + * This function copies at most <code>n</code> bytes to the destination, but
1.59 + * the element is always freed as a whole.
1.60 + * If the element was larger than <code>n</code>, the remaining data is lost.
1.61 *
1.62 * @param stack a pointer to the stack
1.63 * @param dest the location where the contents shall be written to
1.64 - * @param n copies at most n elements to <code>dest</code>
1.65 + * @param n copies at most n bytes to <code>dest</code>
1.66 * @see ucx_stack_pop
1.67 */
1.68 void ucx_stack_popn(UcxStack *stack, void *dest, size_t n);
