Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 2003 - 2007 Pekka Riikonen
+ Copyright (C) 2003 - 2008 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
*
* DESCRIPTION
*
- * Implementation of data stack which can be used to allocate memory from
+ * Data stack interface which can be used to do fast allocations from
* the stack. Basically SilcStack is a pre-allocated memory pool system
* which allows fast memory allocation for routines and applications that
* frequently allocate small amounts of memory. Other advantage of this
* allocation by various routines. Returns the pointer to the stack
* that must be freed with silc_stack_free function when it is not
* needed anymore. If the `stack_size' is zero (0) by default a
- * 1 kilobyte (1024 bytes) stack is allocated. If the `stack_size'
- * is non-zero the byte value must be multiple by 8.
+ * 1 kilobyte (1024 bytes) stack is allocated.
*
* If `parent' is non-NULL the created stack is a child of the `parent'
* stack. All of childs the memory is allocated from the `parent' and
*
* DESCRIPTION
*
- * Push the top of the stack down which becomes the new top of the stack.
+ * 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
*
* DESCRIPTION
*
- * Pop the top of the stack which removes the previous stack frame and
- * becomes the top of the stack. After popping, memory allocated in
+ * Pop the top of the stack to remove the previous stack frame and use
+ * previous frame as top of the stack. After popping, memory allocated in
* the old frame is freed. For each silc_stack_push call there must be
* silc_stack_pop call to free all memory (in reality any memory is not
* freed but within the stack it is). This returns the stack pointer of
* NOTES
*
* This function should be used only if low level memory allocation with
- * SilcStack is needed. Instead, silc_srealloc could be used.
+ * SilcStack is needed. Instead, silc_srealloc could be used which can
+ * handle failed reallocation by allocating new block.
*
***/
void *silc_stack_realloc(SilcStack stack, SilcUInt32 old_size,
***/
SilcBool silc_stack_purge(SilcStack stack);
+/****f* silcutil/SilcStackAPI/silc_stack_set_global
+ *
+ * SYNOPSIS
+ *
+ * void silc_stack_set_global(SilcStack stack);
+ *
+ * DESCRIPTION
+ *
+ * Sets global SilcStack `stack' that can be retrieved at any time
+ * by using silc_stack_get_global. The global stack is global only
+ * to the current thread. Each thread can have their own global stack.
+ * If each thread must have own stack this must be called in each
+ * thread. If the global stack has been set already, new call will
+ * replace the old one.
+ *
+ * This routine is provided only as a convenience function to store
+ * program's or thread's stack in one global place. It is not mandatory
+ * to call this function in order to use SilcStack.
+ *
+ ***/
+void silc_stack_set_global(SilcStack stack);
+
+/****f* silcutil/SilcStackAPI/silc_stack_get_global
+ *
+ * SYNOPSIS
+ *
+ * SilcStack silc_stack_get_global(void);
+ *
+ * DESCRIPTION
+ *
+ * Returns the thread's global stack that was set by calling the
+ * silc_stack_set_global or NULL if global stack has not been set.
+ *
+ ***/
+SilcStack silc_stack_get_global(void);
+
#include "silcstack_i.h"
#endif /* SILCSTACK_H */