istack(3)

Section: Interp SDK (3)
Updated: 2007-02-20

NAME

istack - implements the stack interface used by interp

SYNOPSIS

#include itypes.h
#include istack.h

struct Stack_T {
  iword *ptr;
  iword *start;
  iword *end;
};

typedef struct Stack_T *Stack_T;

Stack_T Stack_new( long nbytes );
void Stack_free( Stack_T stk );
Stack_empty_M(stk)
Stack_full_M(stk)
Stack_depth_M(stk)
Stack_size_M(stk)
Stack_push_M(stk)
Stack_pop_M(stk)
Stack_drop_M(stk)
Stack_get_M(stk)
Stack_get_under_M(stk)
Stack_get_under_under_M(stk)
Stack_pick_M(stk)
Stack_put_M(stk)
Stack_put_under_M(stk)
Stack_put_under_under_M(stk)
Stack_over_M(stk)
Stack_reset_M(stk)

DESCRIPTION

These functions and macros implement a simple stack interface consisting of a list head (containing three pointers) and a one-dimensional array. The first pointer in the list head points to the item currently on the top of the stack. The second pointer points to the base address of the one-dimensional array that is used as the stack. The third pointer points to the next address beyond the end of the stack.

When the stack is empty the first pointer in the list head has a value that is one stack item less than the base address. The stack grows toward high memory. A stack push increments the stack pointer and stores the item. A stack pop reads the item then decrements the stack pointer. Each stack item is of type iword (4-bytes each.)

All the macros expect a single argument of type Stack_T, a pointer to the Stack_T list head structure.

LIST OF FUNCTIONS AND MACROS

Macro/Function

Description

Stack_new

Allocates the list head, and the requested number of bytes for the stack, and returns a pointer to the list head.

Stack_free

Frees both the stack and the list head.

Stack_empty_M

Returns TRUE if the stack is empty, or FALSE otherwise.

Stack_full_M

Returns TRUE if the stack is full, or FALSE otherwise.

Stack_depth_M

Returns the number of items on the stack.

Stack_size_M

Returns the size of the stack in bytes.

Stack_push_M

Increments the stack pointer, then stores an item on it.

Stack_pop_M

Reads the item from the top of the stack and decrements the stack pointer.

Stack_drop_M

Decrements the stack pointer.

Stack_get_M

Reads the item from the top of the stack without disturbing either the stack or the list head.

Stack_get_under_M

Reads the item underneath the top item on the stack without disturbing either the stack or the list head.

Stack_get_under_under_M

Reads the item two items down from the top item on the stack without disturbing either the stack or the list head.

Stack_pick_M

Reads the nth item from the stack without disturbing either the stack or the list head. Item zero (0) is the top item on the stack.

Stack_put_M

Rewrites the top item on the stack without disturbing the list head.

Stack_put_under_M

Rewrites the item underneath the top item on the stack without disturbing the list head.

Stack_put_under_under_M

Rewrites the item two items down from the top item on the stack without disturbing the list head.

Stack_over_M

Reads the item underneath the top item on the stack without disturbing either the stack or the list head.

Stack_reset_M

Resets the stack pointer, effectively emptying the stack.

EXAMPLES OF APPROPRIATE MACRO USAGE

if( Stack_empty_M(cp->frsp) ) ...

if( Stack_full_M(cp->sp) ) ...

if( Stack_depth_M(cp->sp) < 1 ) ...

iword size = Stack_stack_M(cp->lcsp);

Stack_push_M(cp->sp,value);

address = Stack_pop_M(cp->sp);

Stack_drop_M(cp->frsp);

number = Stack_get_M(cp->sp);

local_variable_base_address = Stack_get_under_M(cp->frsp);

temp = Stack_get_under_under_M(cp->sp);

Stack_put_M(cp->sp) = Stack_pick_M(cp->sp, stack_entry_number);

Stack_put_under_M(cp->sp) = Stack_get_M(cp->sp);

Stack_put_under_under_M(cp->sp) = Stack_get_under_M(cp->sp);

temp = Stack_over_M(cp->sp);

Stack_reset_M(cp->sp);