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))
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)
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()