Stack API

Libmodule offers an easy to use stack implementation, provided by <module/stack.h> header.
It is used internally to store module’s stack for become/unbecome methods.

Structures

typedef enum {
    STACK_WRONG_PARAM = -4,
    STACK_MISSING,
    STACK_ERR,
    STACK_OMEM,
    STACK_OK
} stack_ret_code;

/* Callback for stack_iterate */
typedef stack_ret_code (*stack_cb)(void *, void *);

/* Fn for stack_set_dtor */
typedef void (*stack_dtor)(void *);

/* Incomplete struct declaration for stack */
typedef struct _stack stack_t;

/* Incomplete struct declaration for stack iterator */
typedef struct _stack_itr stack_itr_t;

API

Where not specified, these functions return a stack_ret_code.

stack_new(fn)

Create a new stack_t object.

Parameters:

• fn (const stack_dtor) – callback called on value destroy. If NULL, values won’t be automatically destroyed.

Returns:

pointer to newly allocated stack_t.

stack_itr_new(s)

Create a new stack_itr_t object. Note that it can be freed with free().

Parameters:

• s (const stack_t *) – pointer to stack_t

Returns:

pointer to newly allocated stack_itr_t.

stack_itr_next(itr)

Get next iterator. If next iterator is past last element, iterator will be automatically freed.

Parameters:

• itr (stack_itr_t *) – pointer to stack_itr_t

Returns:

pointer to next iterator.

stack_itr_get_data(itr)

Get iterator’s data.

Parameters:

• itr (const stack_itr_t *) – pointer to stack_itr_t

Returns:

pointer to current iterator’s data.

stack_itr_set_data(itr)

Set iterator’s data.

Parameters:

• itr (const stack_itr_t *) – pointer to stack_itr_t

stack_iterate(s, fn, userptr)

Iterate a stack calling cb on each element until STACK_OK is returned (or end of stack is reached). Returns STACK_MISSING if stack is NULL or empty.
If fn() returns a value != STACK_OK, iteration will stop and: if value < STACK_OK, value will be returned, else STACK_OK will be returned.

Parameters:

• s (stack_t *) – pointer to stack_t
• fn (const stack_cb) – callback to be called
• userptr (void *) – userdata to be passed to callback as first parameter

stack_push(s, val)

Push a value on top of stack.

Parameters:

• s (stack_t *) – pointer to stack_t
• val (void *) – value to be put inside stack

stack_pop(s)

Pop a value from top of stack, removing it from stack.

Parameters:

• s (stack_t *) – pointer to stack_t

Returns:

void pointer to value, on NULL on error.

stack_peek(s)

Return top-of-stack element, without removing it.

Parameters:

• s (stack_t *) – pointer to stack_t

Returns:

void pointer to value, on NULL on error.

stack_clear(s)

Clears a stack object by deleting any object inside stack.

Parameters:

• s (stack_t *) – pointer to stack_t

stack_free(s)

Free a stack object (it internally calls stack_clear too).

Parameters:

• s (stack_t *) – pointer to stack_t

stack_length(s)

Get stack length.

Parameters:

• s (stack_t *) – pointer to stack_t

Returns:

stack length or a stack_ret_code if any error happens (stack_t is null).