*/
-/****h* silcutil/SilcStack Interface
+/****h* silcutil/Memory Pool Interface
*
* DESCRIPTION
*
- * Implementation of data stack 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
- * system is that there are no memory leaks, as long as the stack is
- * freed eventually. Since the stack is usually allocated only once this
- * is not an issue.
+ * 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 system is that there are no
+ * memory leaks, as long as the stack is freed eventually. Since the stack
+ * is usually allocated only once this is not an issue.
*
* SilcStack supports stack pushing and popping allowing to push the stack,
* allocate memory and then pop it to free the allocated memory. The freeing
*
* A basic set of utility functions are provided for application that wish
* to use the SilcStack as their primary memory allocation source. The
- * following functions support SilcStack:
+ * following functions (among many others) support SilcStack:
*
* silc_smalloc, silc_smalloc, silc_scalloc, silc_srealloc, silc_smemdup,
* silc_sfree, silc_sstrdup, silc_buffer_salloc, silc_buffer_salloc_size,
* silc_buffer_srealloc, silc_buffer_srealloc_size, silc_buffer_scopy,
* silc_buffer_sclone, silc_buffer_sformat, silc_buffer_sformat_vp,
- * silc_buffer_sstrformat, silc_buffer_senlarge, silc_mp_sinit,
- * silc_dlist_sinit, silc_hash_table_alloc
+ * silc_buffer_sstrformat, silc_buffer_senlarge, silc_dlist_sinit,
+ * silc_hash_table_alloc
*
* The SilcStack is not thread-safe so that same context could be used for
* allocations from multiple threads. It is however safe to create and use
#ifndef SILCSTACK_H
#define SILCSTACK_H
-/****s* silcutil/SilcStackAPI/SilcStack
+/****s* silcutil/SilcStack
*
* NAME
*
***/
typedef struct SilcStackStruct *SilcStack;
-/****s* silcutil/SilcStackAPI/SilcStackFrame
+/****s* silcutil/SilcStackFrame
*
* NAME
*
***/
typedef struct SilcStackFrameStruct SilcStackFrame;
-/****f* silcutil/SilcStackAPI/SilcStackOomHandler
+/****f* silcutil/SilcStackOomHandler
*
* SYNOPSIS
*
***/
typedef void (*SilcStackOomHandler)(SilcStack stack, void *context);
-/****f* silcutil/SilcStackAPI/silc_stack_alloc
+/****f* silcutil/silc_stack_alloc
*
* SYNOPSIS
*
* that, even though child allocates memory from the parent, the parent's
* stack is not consumed.
*
- * Returns NULL on error.
+ * Returns NULL on error and sets silc_errno.
*
***/
SilcStack silc_stack_alloc(SilcUInt32 stack_size, SilcStack parent);
-/****f* silcutil/SilcStackAPI/silc_stack_free
+/****f* silcutil/silc_stack_free
*
* SYNOPSIS
*
***/
void silc_stack_free(SilcStack stack);
-/****f* silcutil/SilcStackAPI/silc_stack_push
+/****f* silcutil/silc_stack_push
*
* SYNOPSIS
*
*
* 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
***/
SilcUInt32 silc_stack_push(SilcStack stack, SilcStackFrame *frame);
-/****f* silcutil/SilcStackAPI/silc_stack_pop
+/****f* silcutil/silc_stack_pop
*
* SYNOPSIS
*
*
* 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
***/
SilcUInt32 silc_stack_pop(SilcStack stack);
-/****f* silcutil/SilcStackAPI/silc_stack_malloc
+/****f* silcutil/silc_stack_malloc
*
* SYNOPSIS
*
***/
void *silc_stack_malloc(SilcStack stack, SilcUInt32 size);
-/****f* silcutil/SilcStackAPI/silc_stack_realloc
+/****f* silcutil/silc_stack_realloc
*
* SYNOPSIS
*
* 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,
void *ptr, SilcUInt32 size);
-/****f* silcutil/SilcStackAPI/silc_stack_set_oom_handler
+/****f* silcutil/silc_stack_set_oom_handler
*
* SYNOPSIS
*
SilcStackOomHandler oom_handler,
void *context);
-/****f* silcutil/SilcStackAPI/silc_stack_set_alignment
+/****f* silcutil/silc_stack_set_alignment
*
* SYNOPSIS
*
***/
void silc_stack_set_alignment(SilcStack stack, SilcUInt32 alignment);
-/****f* silcutil/SilcStackAPI/silc_stack_get_alignment
+/****f* silcutil/silc_stack_get_alignment
*
* SYNOPSIS
*
***/
SilcUInt32 silc_stack_get_alignment(SilcStack stack);
-/****f* silcutil/SilcStackAPI/silc_stack_purge
+/****f* silcutil/silc_stack_purge
*
* SYNOPSIS
*
***/
SilcBool silc_stack_purge(SilcStack stack);
-/****f* silcutil/SilcStackAPI/silc_stack_set_global
+/****f* silcutil/silc_stack_set_global
*
* SYNOPSIS
*
***/
void silc_stack_set_global(SilcStack stack);
-/****f* silcutil/SilcStackAPI/silc_stack_get_global
+/****f* silcutil/silc_stack_get_global
*
* SYNOPSIS
*
projects / runtime.git / blobdiff