X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcstack.h;h=f2663eef949e4b37b8774b9391d85ca56a301d48;hb=8fc3402eeef449d1a0b7dfa10a2f316a181d8a27;hp=c60cd7b7221b76b92855b49ffaa805c39edc6336;hpb=43e2881abed8abfd54a27332e2def0178ddccea5;p=silc.git

diff --git a/lib/silcutil/silcstack.h b/lib/silcutil/silcstack.h
index c60cd7b7..f2663eef 100644
--- a/lib/silcutil/silcstack.h
+++ b/lib/silcutil/silcstack.h
@@ -4,7 +4,7 @@
 
   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
@@ -21,7 +21,7 @@
  *
  * DESCRIPTION
  *
- * Implementation of data stack which can be used to allocate memory from
+ * 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
@@ -125,8 +125,7 @@ typedef void (*SilcStackOomHandler)(SilcStack stack, void *context);
  *    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
@@ -281,16 +280,17 @@ void *silc_stack_malloc(SilcStack stack, SilcUInt32 size);
  * 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
  *
@@ -365,6 +365,61 @@ void silc_stack_set_alignment(SilcStack stack, SilcUInt32 alignment);
  ***/
 SilcUInt32 silc_stack_get_alignment(SilcStack stack);
 
+/****f* silcutil/SilcStackAPI/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/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 */