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

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

size	the approximate payload
elems	the 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

stack

a 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

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.

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)

Returns the size of the top most element.

Parameters

stack

a 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

stack

a 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

stack	a pointer to the stack
nelem	amount of elements to allocate
elsize	amount 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

stack	a pointer to the stack
ptr	a 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

stack	a pointer to an uninitialized stack structure
space	the memory area that shall be managed
size	size 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

stack	a pointer to the stack
n	amount 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

stack	a pointer to the stack
dest	the location where the contents shall be written to
n	copies 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

stack	a pointer to the stack
n	amount of memory to allocate
data	a 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

stack	a pointer to the stack
nelem	amount of elements to allocate
elsize	amount of memory per element
data	a 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

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

Returns

a pointer to the new location of the memory

See also

ucx_allocator_realloc()