silc_stack_push

SYNOPSIS

    SilcUInt32 silc_stack_push(SilcStack stack, SilcStackFrame *frame);

DESCRIPTION

Push the top of the stack and add new stack frame on top of the stack. For every silc_stack_push call there must be silc_stack_pop call. All allocations between these two calls will be done from the top of the stack and all allocated memory is freed after the next silc_stack_pop is called. This returns so called stack pointer for the new stack frame, which the caller may use to check that all calls to silc_stack_pop has been made.

If the `frame' is non-NULL then that SilcStackFrame is used as stack frame. Usually `frame' is set to NULL by user. Statically allocated SilcStackFrame should be used when using silc_stack_push in recursive function and the recursion may become deep. In this case using statically allocated SilcStackFrame is recommended since it assures that frames never run out. If your routine is not recursive then setting `frame' to NULL is recommended.

This function is used when a routine is doing frequent allocations from the stack. If the stack is not pushed and later popped all allocations are made from the stack and the stack eventually runs out (it gets enlarged by normal memory allocation). By pushing and then later popping the frequent allocations does not consume the stack.

If `stack' is NULL this call has no effect. This function does not allocate any memory.

EXAMPLE

    All memory allocations in silc_foo_parse_packet will be done in
    a fresh stack frame and that data is freed after the parsing is
    completed.

    silc_stack_push(stack, NULL);
    silc_foo_parse_packet(packet, stack);
    silc_stack_pop(stack);

    Another example with recursion and using statically allocated
    SilcStackFrame.  After popping the statically allocated frame can
    be reused if necessary.

    void silc_foo_this_function(SilcStack stack)
    {
      SilcStackFrame frame;
      ...
      silc_stack_push(stack, &frame);
      silc_foo_this_function(stack);   // Call recursively
      silc_stack_pop(stack);
      ...
    }