universe@390: universe@390:

Default stack memory allocation implementation. universe@390: More...

universe@390:

#include "ucx.h"
universe@390: #include "allocator.h"
universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Data Structures
struct	UcxStack
	UCX stack structure. More...

struct	ucx_stack_metadata
	Metadata for each UCX stack element. More...

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: 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...

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: 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...

universe@390:

Detailed Description

universe@390:

Default stack memory allocation implementation.

universe@390:

Author: Mike Becker; universe@390: Olaf Wintermann

universe@390:

Macro Definition Documentation

universe@390: universe@390:

◆ ucx_stack_dim

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

#define ucx_stack_dim	(	size,
		elems
	)

universe@390:

universe@390: Value:

(size+sizeof(struct ucx_stack_metadata) * \

(elems + 1))

ucx_stack_metadata

Metadata for each UCX stack element.

Definition: stack.h:69

universe@390:

Computes a recommended size for the stack memory area.

universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

size	the approximate payload
elems	the approximate count of element allocations

universe@390:

Returns: a recommended size for the stack space based on the information provided

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_empty

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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

universe@390:

universe@390: universe@390:

Checks, if the stack is empty.

universe@390:

Parameters

universe@390: universe@390: universe@390:

stack a pointer to the stack

universe@390:

Returns: nonzero, if the stack is empty, zero otherwise

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_pop

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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

universe@390:

universe@390: universe@390:

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

universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

stack	a pointer to the stack
dest	the location where the contents shall be written to, or `NULL`, if the element shall only be removed.

universe@390:

See also: ucx_stack_free; universe@390: ucx_stack_popn

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_topsize

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

#define ucx_stack_topsize ( stack )

universe@390:

universe@390: 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

universe@390:

Returns the size of the top most element.

universe@390:

Parameters

universe@390: universe@390: universe@390:

stack a pointer to the stack

universe@390:

Returns: the size of the top most element

universe@390: universe@390:

universe@390:

Function Documentation

universe@390: universe@390:

◆ ucx_stack_avail()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

size_t ucx_stack_avail ( UcxStack * stack )

universe@390:

universe@390: universe@390:

Returns the remaining available memory on the specified stack.

universe@390:

Parameters

universe@390: universe@390: universe@390:

stack a pointer to the stack

universe@390:

Returns: the remaining available memory

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_calloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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

universe@390:

universe@390: universe@390:

Allocates an array of stack memory.

universe@390:

The content of the allocated memory is set to zero.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

stack	a pointer to the stack
nelem	amount of elements to allocate
elsize	amount of memory per element

universe@390:

Returns: a pointer to the allocated memory

universe@390:

See also: ucx_allocator_calloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_free()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_stack_free	(	UcxStack *	stack,
		void *	ptr
	)

universe@390:

universe@390: universe@390:

Frees memory on the stack.

universe@390:

Freeing stack memory behaves in a special way.

universe@390:

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.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

stack	a pointer to the stack
ptr	a pointer to the memory that shall be freed

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_init()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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

universe@390:

universe@390: universe@390:

Initializes UcxStack structure with memory.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

stack	a pointer to an uninitialized stack structure
space	the memory area that shall be managed
size	size of the memory area

universe@390:

Returns: a new UcxStack structure

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_malloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void* ucx_stack_malloc	(	UcxStack *	stack,
		size_t	n
	)

universe@390:

universe@390: universe@390:

Allocates stack memory.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

stack	a pointer to the stack
n	amount of memory to allocate

universe@390:

Returns: a pointer to the allocated memory or NULL on stack overflow

universe@390:

See also: ucx_allocator_malloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_popn()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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

universe@390:

universe@390: universe@390:

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

universe@390:

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.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

stack	a pointer to the stack
dest	the location where the contents shall be written to
n	copies at most n bytes to `dest`

universe@390:

See also: ucx_stack_pop

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_push()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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

universe@390:

universe@390: universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

stack	a pointer to the stack
n	amount of memory to allocate
data	a pointer to the data to copy

universe@390:

Returns: a pointer to the allocated memory

universe@390:

See also: ucx_stack_malloc

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_pusharr()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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

universe@390:

universe@390: universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

stack	a pointer to the stack
nelem	amount of elements to allocate
elsize	amount of memory per element
data	a pointer to the data

universe@390:

Returns: a pointer to the allocated memory

universe@390:

See also: ucx_stack_calloc

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_stack_realloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

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

universe@390:

universe@390: universe@390:

Reallocates memory on the stack.

universe@390:

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

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

stack	the stack
ptr	a pointer to the memory that shall be reallocated
n	the new size of the memory

universe@390:

Returns: a pointer to the new location of the memory

universe@390:

See also: ucx_allocator_realloc()

universe@390: universe@390:

universe@390:

universe@390: Data Structures

universe@390: Macros

universe@390: Functions

Detailed Description

Macro Definition Documentation

◆ ucx_stack_dim

◆ ucx_stack_empty

◆ ucx_stack_pop

◆ ucx_stack_topsize

Function Documentation

◆ ucx_stack_avail()

◆ ucx_stack_calloc()

◆ ucx_stack_free()

◆ ucx_stack_init()

◆ ucx_stack_malloc()

◆ ucx_stack_popn()

◆ ucx_stack_push()

◆ ucx_stack_pusharr()

◆ ucx_stack_realloc()