diff -r 92e482410453 -r d345541018fa docs/api-2.1/stack_8h.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api-2.1/stack_8h.html Sat Feb 06 19:11:44 2021 +0100 @@ -0,0 +1,677 @@ + + + + + + + +ucx: /home/mike/workspace/c/ucx/src/ucx/stack.h File Reference + + + + + + + + + +
+
+ + + + + + + +
+
ucx +
+
UAP Common Extensions
+
+
+ + + + + + + + +
+
+ + +
+ +
+ + +
+
+
+Data Structures | +Macros | +Functions
+
+
stack.h File Reference
+
+
+ +

Default stack memory allocation implementation. +More...

+
#include "ucx.h"
+#include "allocator.h"
+
+

Go to the source code of this file.

+ + + + + + + + +

+Data Structures

struct  UcxStack
 UCX stack structure. More...
 
struct  ucx_stack_metadata
 Metadata for each UCX stack element. More...
 
+ + + + + + + + + + + + + +

+Macros

#define ucx_stack_topsize(stack)
 Returns the size of the top most element. More...
 
#define ucx_stack_pop(stack, dest)   ucx_stack_popn(stack, dest, (size_t)-1)
 Removes the top most element from the stack and copies the content to dest, if specified. More...
 
#define ucx_stack_empty(stack)   (!(stack)->top)
 Checks, if the stack is empty. More...
 
#define ucx_stack_dim(size, elems)
 Computes a recommended size for the stack memory area. More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

void ucx_stack_init (UcxStack *stack, char *space, size_t size)
 Initializes UcxStack structure with memory. More...
 
void * ucx_stack_malloc (UcxStack *stack, size_t n)
 Allocates stack memory. More...
 
void * ucx_stack_push (UcxStack *stack, size_t n, const void *data)
 Allocates memory with ucx_stack_malloc() and copies the specified data if the allocation was successful. More...
 
void * ucx_stack_calloc (UcxStack *stack, size_t nelem, size_t elsize)
 Allocates an array of stack memory. More...
 
void * ucx_stack_pusharr (UcxStack *stack, size_t nelem, size_t elsize, const void *data)
 Allocates memory with ucx_stack_calloc() and copies the specified data if the allocation was successful. More...
 
void * ucx_stack_realloc (UcxStack *stack, void *ptr, size_t n)
 Reallocates memory on the stack. More...
 
void ucx_stack_free (UcxStack *stack, void *ptr)
 Frees memory on the stack. More...
 
void ucx_stack_popn (UcxStack *stack, void *dest, size_t n)
 Removes the top most element from the stack and copies the content to dest. More...
 
size_t ucx_stack_avail (UcxStack *stack)
 Returns the remaining available memory on the specified stack. More...
 
+

Detailed Description

+

Default stack memory allocation implementation.

+
Author
Mike Becker
+
+Olaf Wintermann
+

Macro Definition Documentation

+ +

◆ ucx_stack_dim

+ +
+
+ + + + + + + + + + + + + + + + + + +
#define ucx_stack_dim( size,
 elems 
)
+
+Value:
(size+sizeof(struct ucx_stack_metadata) * \
(elems + 1))
ucx_stack_metadata
Metadata for each UCX stack element.
Definition: stack.h:69
+
+

Computes a recommended size for the stack memory area.

+

Note, that reallocations have not been taken into account, so you might need to reserve twice as much memory to allow many reallocations.

+
Parameters
+ + + +
sizethe approximate payload
elemsthe approximate count of element allocations
+
+
+
Returns
a recommended size for the stack space based on the information provided
+ +
+
+ +

◆ ucx_stack_empty

+ +
+
+ + + + + + + + +
#define ucx_stack_empty( stack)   (!(stack)->top)
+
+ +

Checks, if the stack is empty.

+
Parameters
+ + +
stacka pointer to the stack
+
+
+
Returns
nonzero, if the stack is empty, zero otherwise
+ +
+
+ +

◆ ucx_stack_pop

+ +
+
+ + + + + + + + + + + + + + + + + + +
#define ucx_stack_pop( stack,
 dest 
)   ucx_stack_popn(stack, dest, (size_t)-1)
+
+ +

Removes the top most element from the stack and copies the content to dest, if specified.

+

Use ucx_stack_topsize()# to get the amount of memory that must be available at the location of dest.

+
Parameters
+ + + +
stacka pointer to the stack
destthe location where the contents shall be written to, or NULL, if the element shall only be removed.
+
+
+
See also
ucx_stack_free
+
+ucx_stack_popn
+ +
+
+ +

◆ ucx_stack_topsize

+ +
+
+ + + + + + + + +
#define ucx_stack_topsize( stack)
+
+Value:
((stack)->top ? ((struct ucx_stack_metadata*)\
(stack)->top - 1)->size : 0)
ucx_stack_metadata
Metadata for each UCX stack element.
Definition: stack.h:69
+
+

Returns the size of the top most element.

+
Parameters
+ + +
stacka pointer to the stack
+
+
+
Returns
the size of the top most element
+ +
+
+

Function Documentation

+ +

◆ ucx_stack_avail()

+ +
+
+ + + + + + + + +
size_t ucx_stack_avail (UcxStack * stack)
+
+ +

Returns the remaining available memory on the specified stack.

+
Parameters
+ + +
stacka pointer to the stack
+
+
+
Returns
the remaining available memory
+ +
+
+ +

◆ ucx_stack_calloc()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
void* ucx_stack_calloc (UcxStack * stack,
size_t nelem,
size_t elsize 
)
+
+ +

Allocates an array of stack memory.

+

The content of the allocated memory is set to zero.

+
Parameters
+ + + + +
stacka pointer to the stack
nelemamount of elements to allocate
elsizeamount of memory per element
+
+
+
Returns
a pointer to the allocated memory
+
See also
ucx_allocator_calloc()
+ +
+
+ +

◆ ucx_stack_free()

+ +
+
+ + + + + + + + + + + + + + + + + + +
void ucx_stack_free (UcxStack * stack,
void * ptr 
)
+
+ +

Frees memory on the stack.

+

Freeing stack memory behaves in a special way.

+

If the element, that should be freed, is the top most element of the stack, it is removed from the stack. Otherwise it is marked as freed. Marked elements are removed, when they become the top most elements of the stack.

+
Parameters
+ + + +
stacka pointer to the stack
ptra pointer to the memory that shall be freed
+
+
+ +
+
+ +

◆ ucx_stack_init()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
void ucx_stack_init (UcxStack * stack,
char * space,
size_t size 
)
+
+ +

Initializes UcxStack structure with memory.

+
Parameters
+ + + + +
stacka pointer to an uninitialized stack structure
spacethe memory area that shall be managed
sizesize of the memory area
+
+
+
Returns
a new UcxStack structure
+ +
+
+ +

◆ ucx_stack_malloc()

+ +
+
+ + + + + + + + + + + + + + + + + + +
void* ucx_stack_malloc (UcxStack * stack,
size_t n 
)
+
+ +

Allocates stack memory.

+
Parameters
+ + + +
stacka pointer to the stack
namount of memory to allocate
+
+
+
Returns
a pointer to the allocated memory or NULL on stack overflow
+
See also
ucx_allocator_malloc()
+ +
+
+ +

◆ ucx_stack_popn()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
void ucx_stack_popn (UcxStack * stack,
void * dest,
size_t n 
)
+
+ +

Removes the top most element from the stack and copies the content to dest.

+

This function copies at most n bytes to the destination, but the element is always freed as a whole. If the element was larger than n, the remaining data is lost.

+
Parameters
+ + + + +
stacka pointer to the stack
destthe location where the contents shall be written to
ncopies at most n bytes to dest
+
+
+
See also
ucx_stack_pop
+ +
+
+ +

◆ ucx_stack_push()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
void* ucx_stack_push (UcxStack * stack,
size_t n,
const void * data 
)
+
+ +

Allocates memory with ucx_stack_malloc() and copies the specified data if the allocation was successful.

+
Parameters
+ + + + +
stacka pointer to the stack
namount of memory to allocate
dataa pointer to the data to copy
+
+
+
Returns
a pointer to the allocated memory
+
See also
ucx_stack_malloc
+ +
+
+ +

◆ ucx_stack_pusharr()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
void* ucx_stack_pusharr (UcxStack * stack,
size_t nelem,
size_t elsize,
const void * data 
)
+
+ +

Allocates memory with ucx_stack_calloc() and copies the specified data if the allocation was successful.

+
Parameters
+ + + + + +
stacka pointer to the stack
nelemamount of elements to allocate
elsizeamount of memory per element
dataa pointer to the data
+
+
+
Returns
a pointer to the allocated memory
+
See also
ucx_stack_calloc
+ +
+
+ +

◆ ucx_stack_realloc()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
void* ucx_stack_realloc (UcxStack * stack,
void * ptr,
size_t n 
)
+
+ +

Reallocates memory on the stack.

+

Shrinking memory is always safe. Extending memory can be very expensive.

+
Parameters
+ + + + +
stackthe stack
ptra pointer to the memory that shall be reallocated
nthe new size of the memory
+
+
+
Returns
a pointer to the new location of the memory
+
See also
ucx_allocator_realloc()
+ +
+
+
+ +
+Generated on Thu Dec 19 2019 19:58:24 for ucx by   +doxygen + 1.8.13 +
+ +