#include "vl_buffer.h"

Include dependency graph for vl_stack.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	vl_stack
	A virtual stack allocator. More...

Macros
#define	vlStackSize(stackPtr) ((stackPtr)->depth)
	Returns the size of the specified stack.

#define	vlStackEmpty(stackPtr) ((stackPtr)->depth == 0)
	Returns a boolean indicating if the specified stack is empty.

Typedefs
typedef vl_dsoffs_t	vl_stack_offset

Functions
void	vlStackInit (vl_stack *stack)

void	vlStackFree (vl_stack *stack)
	Frees the specified stack instance's allocation.

vl_stack *	vlStackNew ()
	Allocates on the heap, initializes, and returns a stack allocator instance.

void	vlStackDelete (vl_stack *stack)
	Deletes the specified stack. This stack allocator should be initialized via vlStackNew.

void	vlStackReset (vl_stack *stack)
	Resets the specified stack allocator, allowing it to be used as if it had just been initialized.

vl_stack_offset	vlStackPush (vl_stack *stack, vl_memsize_t size)
	Reserves a new block of memory at the top of the stack, returning its offset.

vl_stack_offset	vlStackPushValue (vl_stack stack, const void data, vl_memsize_t size)
	Reserves and assigns new block of memory at the top of the stack, returning its offset.

vl_transient *	vlStackPeek (vl_stack *stack)
	Returns a pointer to the top level of the stack.

vl_memsize_t	vlStackPeekSize (vl_stack *stack)
	Returns the size of the top level of the stack, in bytes.

vl_transient *	vlStackSample (vl_stack *stack, vl_stack_offset offset)
	Samples the stack at the specified offset.

vl_memsize_t	vlStackSampleSize (vl_stack *stack, vl_stack_offset offset)
	Samples the size of the stack level at the specified offset.

void	vlStackPop (vl_stack *stack)
	Pops the top level of the stack, allowing it to be overwritten in the future.

Data Structure Documentation

◆ vl_stack

struct vl_stack

A virtual stack allocator.

The vl_stack structure represents a stack allocator data structure. It is built on top of the vl_buffer structure, which manages dynamic resizing.

This structure might not be be quite as easy to use as you might anticipate, due to the necessity to explicitly define the size of each level of the stack in bytes. This should be fairly easy to define using sizeof() or simply computing the size.

This structure also allows for sampling properties low in the stack, if an appropriate offset is given. Many stack data structure implementations prohibit this, however there are notable applications for this kind of use.

Collaboration diagram for vl_stack:

Data Fields
vl_buffer	buffer
vl_dsidx_t	depth
vl_uintptr_t	headOffset

Macro Definition Documentation

◆ vlStackEmpty

#define vlStackEmpty ( stackPtr ) ((stackPtr)->depth == 0)

Returns a boolean indicating if the specified stack is empty.

Parameters

stackPtr pointer

Complexity of O(1) constant.

Returns: 0 if stack has elements, 1 if stack is empty.

◆ vlStackSize

#define vlStackSize ( stackPtr ) ((stackPtr)->depth)

Returns the size of the specified stack.

Parameters

stackPtr pointer

Complexity of O(1) constant.

Returns: size of the stack

Typedef Documentation

◆ vl_stack_offset

typedef vl_dsoffs_t vl_stack_offset

Function Documentation

◆ vlStackDelete()

void vlStackDelete ( vl_stack * stack )

Deletes the specified stack. This stack allocator should be initialized via vlStackNew.

See also: vlStackNew

Parameters

stack pointer

Complexity of O(1) constant.

Here is the call graph for this function:

◆ vlStackFree()

void vlStackFree ( vl_stack * stack )

Frees the specified stack instance's allocation.

Frees the specified stack allocator. This stack allocator should first be initialized via vlStackInit.

See also: vlStackInit

Parameters

stack pointer

Complexity of O(1) constant.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlStackInit()

void vlStackInit ( vl_stack * stack )

Initializes the underlying memory of an existing vl_stack pointer. The stack allocator should be freed with vlStackFree.

Parameters

stack stack pointer

See also: vlStackFree

Complexity of O(1) constant.

Here is the caller graph for this function:

◆ vlStackNew()

vl_stack * vlStackNew ( )

Allocates on the heap, initializes, and returns a stack allocator instance.

See also: vlStackDelete

Complexity of O(1) constant.

Returns: stack allocator pointer located on the heap.

Here is the call graph for this function:

◆ vlStackPeek()

vl_transient * vlStackPeek ( vl_stack * stack )

Returns a pointer to the top level of the stack.

Results in undefined behavior if the stack is empty.

Parameters

stack pointer

Complexity of O(1) constant.

Returns: pointer to the top level of the stack.

Here is the caller graph for this function:

◆ vlStackPeekSize()

vl_memsize_t vlStackPeekSize ( vl_stack * stack )

Returns the size of the top level of the stack, in bytes.

Results in undefined behavior if the stack is empty.

Parameters

stack pointer

Complexity of O(1) constant.

Returns: size of the top level of the stack, in bytes.

◆ vlStackPop()

void vlStackPop ( vl_stack * stack )

Pops the top level of the stack, allowing it to be overwritten in the future.

Parameters

stack

Complexity of O(1) constant.

Here is the caller graph for this function:

◆ vlStackPush()

vl_stack_offset vlStackPush	(	vl_stack *	stack,
		vl_memsize_t	size )

Reserves a new block of memory at the top of the stack, returning its offset.

This may force the underlying buffer to grow in size, which may invalidate the result of all prior calls to vlStackPeek and vlStackSample.

See also: vlStackPeek; vlStackPeekSize; vlStackSample; vlStackSampleSize

Parameters

stack	pointer
size	total bytes in the reserved block

Complexity of O(1) constant.

Returns: offset of the pushed stack level.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlStackPushValue()

vl_stack_offset vlStackPushValue	(	vl_stack *	stack,
		const void *	data,
		vl_memsize_t	size )

Reserves and assigns new block of memory at the top of the stack, returning its offset.

This may force the underlying buffer to grow in size, which may invalidate the result of all prior calls to vlStackPeek and vlStackSample.

See also: vlStackPeek; vlStackPeekSize; vlStackSample; vlStackSampleSize

Parameters

stack	pointer
data	pointer to the element data
size	total bytes in the reserved block

Complexity of O(1) constant.

Returns: offset of the pushed stack level.

Here is the call graph for this function:

◆ vlStackReset()

void vlStackReset ( vl_stack * stack )

Resets the specified stack allocator, allowing it to be used as if it had just been initialized.

This does NOT modify any of the information in the underlying buffer, but rather resets some variables used for book-keeping.

Parameters

stack pointer

Complexity of O(1) constant.

Here is the caller graph for this function:

◆ vlStackSample()

vl_transient * vlStackSample	(	vl_stack *	stack,
		vl_stack_offset	offset )

Samples the stack at the specified offset.

Results in undefined behavior if the offset is invalid.

Parameters

stack	pointer
offset	level of the stack to sample

Complexity of O(1) constant.

Returns: pointer to memory managed by the stack allocator.

Here is the caller graph for this function:

◆ vlStackSampleSize()

vl_memsize_t vlStackSampleSize	(	vl_stack *	stack,
		vl_stack_offset	offset )

Samples the size of the stack level at the specified offset.

Results in undefined behavior if the specified offset is invalid.

Parameters

stack	pointer
offset	level of the stack

Complexity of O(1) constant.

Returns: size of the specified level of the stack, in bytes.

Data Structures

Macros

Typedefs

Functions

Data Structure Documentation

◆ vl_stack

Macro Definition Documentation

◆ vlStackEmpty

◆ vlStackSize

Typedef Documentation

◆ vl_stack_offset

Function Documentation

◆ vlStackDelete()

◆ vlStackFree()

◆ vlStackInit()

◆ vlStackNew()

◆ vlStackPeek()

◆ vlStackPeekSize()

◆ vlStackPop()

◆ vlStackPush()

◆ vlStackPushValue()

◆ vlStackReset()

◆ vlStackSample()

◆ vlStackSampleSize()