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
*/
-/****h* silcutil/SilcStack Interface
+/****h* silcutil/Memory Pool Interface
*
* DESCRIPTION
*
- * Implementation of data stack which can be used to allocate memory 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
*
* 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
* 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
*
* void *silc_stack_realloc(SilcStack stack, SilcUInt32 old_size,
- * *void *ptr, SilcUInt32 size);
+ * void *ptr, SilcUInt32 size);
*
* DESCRIPTION
*
* Attempts to reallocate memory by changing the size of the `ptr' into
* `size'. This routine works only if the previous allocation to `stack'
* was `ptr'. If there is another memory allocation between allocating
- * `ptr' and this call this routine will return NULL. NULL is also
- * returned if the `size' does not fit into the current stack block.
- * If NULL is returned the old memory remains intact.
+ * `ptr' and this call this routine will return NULL (and silc_errno is
+ * set to SILC_ERR_INVALID_ARGUMENT). NULL is also returned if the `size'
+ * does not fit into the current stack block. If NULL is returned the old
+ * memory remains intact.
*
* 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/silc_stack_purge
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_stack_purge(SilcStack stack);
+ *
+ * DESCRIPTION
+ *
+ * Purges the `stack' from extra unused memory. This purges only `stack'
+ * and not its parent if `stack' is a child. This purges only large
+ * allocations. The 1024, 2048, 4096 and 8192 bytes of allocations remain.
+ * Call this multiple times to purge even more. Returns FALSE when there
+ * is no more to purge. This does not purge memory blocks that currently
+ * have allocations. No memory allocations from the stack are lost, so
+ * this is always safe to call.
+ *
+ ***/
+SilcBool silc_stack_purge(SilcStack stack);
+
+/****f* silcutil/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/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 */
projects / runtime.git / blobdiff