lib/silcutil/silcstack.h

   1 /*
   2
   3   silcstack.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2003 - 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SilcStack Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Implementation of data stack which can be used to do fast allocations from
  25  * the stack.  Basically SilcStack is a pre-allocated memory pool system
  26  * which allows fast memory allocation for routines and applications that
  27  * frequently allocate small amounts of memory.  Other advantage of this
  28  * system is that there are no memory leaks, as long as the stack is
  29  * freed eventually.  Since the stack is usually allocated only once this
  30  * is not an issue.
  31  *
  32  * SilcStack supports stack pushing and popping allowing to push the stack,
  33  * allocate memory and then pop it to free the allocated memory.  The freeing
  34  * does not actually do any real memory freeing so it is optimized for
  35  * performance.  The memory alignment may also be specified by user for
  36  * the stack.  This allows the caller to use special alignment for memory
  37  * allocations, if needed.
  38  *
  39  * SilcStack is also a full featured memory pool which allows user to group
  40  * together multiple stacks.  Child stacks may be created from a parent stack
  41  * without consuming the parent stack.  When the child is freed, its memory
  42  * is returned back to the parent and can be used again by other childs.
  43  * It is also possible to create child stacks from another child stack.
  44  *
  45  * A basic set of utility functions are provided for application that wish
  46  * to use the SilcStack as their primary memory allocation source.  The
  47  * following functions support SilcStack:
  48  *
  49  * silc_smalloc, silc_smalloc, silc_scalloc, silc_srealloc, silc_smemdup,
  50  * silc_sfree, silc_sstrdup, silc_buffer_salloc, silc_buffer_salloc_size,
  51  * silc_buffer_srealloc, silc_buffer_srealloc_size, silc_buffer_scopy,
  52  * silc_buffer_sclone, silc_buffer_sformat, silc_buffer_sformat_vp,
  53  * silc_buffer_sstrformat, silc_buffer_senlarge, silc_mp_sinit,
  54  * silc_dlist_sinit, silc_hash_table_alloc
  55  *
  56  * The SilcStack is not thread-safe so that same context could be used for
  57  * allocations from multiple threads.  It is however safe to create and use
  58  * child stacks in a different thread from the parent stack.  Each thread
  59  * should allocate their own SilcStack, however they may be child stacks.
  60  *
  61  ***/
  62
  63 #ifndef SILCSTACK_H
  64 #define SILCSTACK_H
  65
  66 /****s* silcutil/SilcStackAPI/SilcStack
  67  *
  68  * NAME
  69  *
  70  *    typedef struct SilcStackStruct *SilcStack;
  71  *
  72  * DESCRIPTION
  73  *
  74  *    This context represents the stack and it is allocated by
  75  *    silc_stack_alloc and is destroyed with silc_stack_free functions.
  76  *    The context is given as argument to all routines that use this
  77  *    stack allocation library.
  78  *
  79  ***/
  80 typedef struct SilcStackStruct *SilcStack;
  81
  82 /****s* silcutil/SilcStackAPI/SilcStackFrame
  83  *
  84  * NAME
  85  *
  86  *    typedef struct SilcStackFrameStruct SilcStackFrame;
  87  *
  88  * DESCRIPTION
  89  *
  90  *    Static stack frame context that optionally can be used as stack
  91  *    frame in SilcStack.  By default silc_stack_push use pre-allocated
  92  *    stack frame, but user may also use statically allocated SilcStackFrame
  93  *    instead.  This is recommended when using SilcStack in recursive routine
  94  *    and the recursion may become deep.  Using static frame assures that
  95  *    during recursion frames never run out.
  96  *
  97  ***/
  98 typedef struct SilcStackFrameStruct SilcStackFrame;
  99
 100 /****f* silcutil/SilcStackAPI/SilcStackOomHandler
 101  *
 102  * SYNOPSIS
 103  *
 104  *    typedef void (*SilcStackOomHandler)(SilcStack stack, void *context);
 105  *
 106  * DESCRIPTION
 107  *
 108  *    Callback of this type can be given to silc_stack_set_oom_handler
 109  *    to set Out of Memory handler to `stack'.  If memory allocation from
 110  *    `stack' fails this callback is called to indicate error.  The `context'
 111  *    is the context given to silc_stack_set_oom_handler.
 112  *
 113  ***/
 114 typedef void (*SilcStackOomHandler)(SilcStack stack, void *context);
 115
 116 /****f* silcutil/SilcStackAPI/silc_stack_alloc
 117  *
 118  * SYNOPSIS
 119  *
 120  *    SilcStack silc_stack_alloc(SilcUInt32 stack_size, SilcStack parent);
 121  *
 122  * DESCRIPTION
 123  *
 124  *    Allocates new data stack that can be used as stack for fast memory
 125  *    allocation by various routines.  Returns the pointer to the stack
 126  *    that must be freed with silc_stack_free function when it is not
 127  *    needed anymore.  If the `stack_size' is zero (0) by default a
 128  *    1 kilobyte (1024 bytes) stack is allocated.
 129  *
 130  *    If `parent' is non-NULL the created stack is a child of the `parent'
 131  *    stack.  All of childs the memory is allocated from the `parent' and
 132  *    will be returned back to the parent when the child is freed.  Note
 133  *    that, even though child allocates memory from the parent, the parent's
 134  *    stack is not consumed.
 135  *
 136  *    Returns NULL on error.
 137  *
 138  ***/
 139 SilcStack silc_stack_alloc(SilcUInt32 stack_size, SilcStack parent);
 140
 141 /****f* silcutil/SilcStackAPI/silc_stack_free
 142  *
 143  * SYNOPSIS
 144  *
 145  *    void silc_stack_free(SilcStack stack);
 146  *
 147  * DESCRIPTION
 148  *
 149  *    Frees the data stack context.  The stack cannot be used anymore after
 150  *    this and all allocated memory are freed.
 151  *
 152  *    If `stack' is a child stack, its memory is returned back to its
 153  *    parent.  If `stack' is NULL this function does nothing.
 154  *
 155  ***/
 156 void silc_stack_free(SilcStack stack);
 157
 158 /****f* silcutil/SilcStackAPI/silc_stack_push
 159  *
 160  * SYNOPSIS
 161  *
 162  *    SilcUInt32 silc_stack_push(SilcStack stack, SilcStackFrame *frame);
 163  *
 164  * DESCRIPTION
 165  *
 166  *    Push the top of the stack down which becomes the new top of the stack.
 167  *    For every silc_stack_push call there must be silc_stack_pop call.  All
 168  *    allocations between these two calls will be done from the top of the
 169  *    stack and all allocated memory is freed after the next silc_stack_pop
 170  *    is called.  This returns so called stack pointer for the new stack
 171  *    frame, which the caller may use to check that all calls to
 172  *    silc_stack_pop has been made.
 173  *
 174  *    If the `frame' is non-NULL then that SilcStackFrame is used as
 175  *    stack frame.  Usually `frame' is set to NULL by user.  Statically
 176  *    allocated SilcStackFrame should be used when using silc_stack_push
 177  *    in recursive function and the recursion may become deep.  In this
 178  *    case using statically allocated SilcStackFrame is recommended since
 179  *    it assures that frames never run out.  If your routine is not recursive
 180  *    then setting `frame' to NULL is recommended.
 181  *
 182  *    This function is used when a routine is doing frequent allocations
 183  *    from the stack.  If the stack is not pushed and later popped all
 184  *    allocations are made from the stack and the stack eventually runs out
 185  *    (it gets enlarged by normal memory allocation).  By pushing and then
 186  *    later popping the frequent allocations does not consume the stack.
 187  *
 188  *    If `stack' is NULL this call has no effect.  This function does not
 189  *    allocate any memory.
 190  *
 191  * EXAMPLE
 192  *
 193  *    All memory allocations in silc_foo_parse_packet will be done in
 194  *    a fresh stack frame and that data is freed after the parsing is
 195  *    completed.
 196  *
 197  *    silc_stack_push(stack, NULL);
 198  *    silc_foo_parse_packet(packet, stack);
 199  *    silc_stack_pop(stack);
 200  *
 201  *    Another example with recursion and using statically allocated
 202  *    SilcStackFrame.  After popping the statically allocated frame can
 203  *    be reused if necessary.
 204  *
 205  *    void silc_foo_this_function(SilcStack stack)
 206  *    {
 207  *      SilcStackFrame frame;
 208  *      ...
 209  *      silc_stack_push(stack, &frame);
 210  *      silc_foo_this_function(stack);   // Call recursively
 211  *      silc_stack_pop(stack);
 212  *      ...
 213  *    }
 214  *
 215  ***/
 216 SilcUInt32 silc_stack_push(SilcStack stack, SilcStackFrame *frame);
 217
 218 /****f* silcutil/SilcStackAPI/silc_stack_pop
 219  *
 220  * SYNOPSIS
 221  *
 222  *    SilcUInt32 silc_stack_pop(SilcStack stack);
 223  *
 224  * DESCRIPTION
 225  *
 226  *    Pop the top of the stack which removes the previous stack frame and
 227  *    becomes the top of the stack.  After popping, memory allocated in
 228  *    the old frame is freed.  For each silc_stack_push call there must be
 229  *    silc_stack_pop call to free all memory (in reality any memory is not
 230  *    freed but within the stack it is).  This returns the stack pointer of
 231  *    old frame after popping and caller may check that it is same as
 232  *    returned by the silc_stack_push.  If it they differ, some routine
 233  *    has called silc_stack_push but has not called silc_stack_pop, or
 234  *    silc_stack_pop has been called too many times.  Application should
 235  *    treat this as a fatal error, as it is a bug in the application code.
 236  *
 237  *    If `stack' is NULL this call has no effect.   This function does not
 238  *    allocate any memory.
 239  *
 240  * EXAMPLE
 241  *
 242  *    This example saves the stack pointer which is checked when popping
 243  *    the current stack frame.  If the stack pointer differs then someone
 244  *    has pushed the stack frame but forgot to pop it (or has called it
 245  *    too many times).
 246  *
 247  *    sp = silc_stack_push(stack, NULL);
 248  *    silc_foo_parse_packet(packet, stack);
 249  *    if (silc_stack_pop(stack) != sp)
 250  *      fatal("corrupted stack");
 251  *
 252  ***/
 253 SilcUInt32 silc_stack_pop(SilcStack stack);
 254
 255 /****f* silcutil/SilcStackAPI/silc_stack_malloc
 256  *
 257  * SYNOPSIS
 258  *
 259  *    void *silc_stack_malloc(SilcStack stack, SilcUInt32 size);
 260  *
 261  * DESCRIPTION
 262  *
 263  *    Low level memory allocation routine.  Allocates memory block of size of
 264  *    `size' from the `stack'.  The allocated memory is aligned so it can be
 265  *    used to allocate memory for structures, for example.  Returns the
 266  *    allocated memory address or NULL if memory could not be allocated from
 267  *    the `stack'.
 268  *
 269  * NOTES
 270  *
 271  *    This function should be used only if low level memory allocation with
 272  *    SilcStack is needed.  Instead, silc_smalloc and silc_scalloc could
 273  *    be used.
 274  *
 275  ***/
 276 void *silc_stack_malloc(SilcStack stack, SilcUInt32 size);
 277
 278 /****f* silcutil/SilcStackAPI/silc_stack_realloc
 279  *
 280  * SYNOPSIS
 281  *
 282  *    void *silc_stack_realloc(SilcStack stack, SilcUInt32 old_size,
 283  *                             void *ptr, SilcUInt32 size);
 284  *
 285  * DESCRIPTION
 286  *
 287  *    Attempts to reallocate memory by changing the size of the `ptr' into
 288  *    `size'.  This routine works only if the previous allocation to `stack'
 289  *    was `ptr'.  If there is another memory allocation between allocating
 290  *    `ptr' and this call this routine will return NULL (and silc_errno is
 291  *    set to SILC_ERR_INVALID_ARGUMENT).  NULL is also returned if the `size'
 292  *    does not fit into the current stack block.  If NULL is returned the old
 293  *    memory remains intact.
 294  *
 295  * NOTES
 296  *
 297  *    This function should be used only if low level memory allocation with
 298  *    SilcStack is needed.  Instead, silc_srealloc could be used.
 299  *
 300  ***/
 301 void *silc_stack_realloc(SilcStack stack, SilcUInt32 old_size,
 302                          void *ptr, SilcUInt32 size);
 303
 304 /****f* silcutil/SilcStackAPI/silc_stack_set_oom_handler
 305  *
 306  * SYNOPSIS
 307  *
 308  *    void silc_stack_set_oom_handler(SilcStack stack,
 309  *                                    SilcStackOomHandler oom_handler,
 310  *                                    void *context);
 311  *
 312  * DESCRIPTION
 313  *
 314  *    Sets Out of Memory handler `oom_handler' to `stack' to be called
 315  *    if memory allocation from `stack' fails.  The `context' is delivered
 316  *    to `oom_handler'.
 317  *
 318  *    Usually Out of Memory handler is set only when failed memory allocation
 319  *    is a fatal error.  In this case the application would abort() inside
 320  *    the `oom_handler'.  It may also be set if in case of failed allocation
 321  *    application wants to do clean up properly.
 322  *
 323  ***/
 324 void silc_stack_set_oom_handler(SilcStack stack,
 325                                 SilcStackOomHandler oom_handler,
 326                                 void *context);
 327
 328 /****f* silcutil/SilcStackAPI/silc_stack_set_alignment
 329  *
 330  * SYNOPSIS
 331  *
 332  *    void silc_stack_set_alignment(SilcStack stack, SilcUInt32 alignment);
 333  *
 334  * DESCRIPTION
 335  *
 336  *    Sets/changes the memory alignment in the `stack' to `alignment' which
 337  *    is the alignment in bytes.  By default, the SilcStack will use alignment
 338  *    suited for the platform where it is used.  This function can be used
 339  *    to change this alignment, if such change is needed.  You may check the
 340  *    current alignment by calling silc_stack_get_alignment.
 341  *
 342  * NOTES
 343  *
 344  *    It is not mandatory to call this function.  By default the SilcStack
 345  *    will always use alignment suited for the used platform.  This function
 346  *    should be called only if the alignment needs to be changed to something
 347  *    other than the default on the used platform.  For example, some
 348  *    hardware device, such as crypto accelerator, may require special
 349  *    alignment.
 350  *
 351  ***/
 352 void silc_stack_set_alignment(SilcStack stack, SilcUInt32 alignment);
 353
 354 /****f* silcutil/SilcStackAPI/silc_stack_get_alignment
 355  *
 356  * SYNOPSIS
 357  *
 358  *    SilcUInt32 silc_stack_get_alignment(SilcStack stack);
 359  *
 360  * DESCRIPTION
 361  *
 362  *    Returns the memory alignment used with `stack'.  The alignment is in
 363  *    bytes.
 364  *
 365  ***/
 366 SilcUInt32 silc_stack_get_alignment(SilcStack stack);
 367
 368 /****f* silcutil/SilcStackAPI/silc_stack_purge
 369  *
 370  * SYNOPSIS
 371  *
 372  *    SilcBool silc_stack_purge(SilcStack stack);
 373  *
 374  * DESCRIPTION
 375  *
 376  *    Purges the `stack' from extra unused memory.  This purges only `stack'
 377  *    and not its parent if `stack' is a child.  This purges only large
 378  *    allocations.  The 1024, 2048, 4096 and 8192 bytes of allocations remain.
 379  *    Call this multiple times to purge even more.  Returns FALSE when there
 380  *    is no more to purge.  This does not purge memory blocks that currently
 381  *    have allocations.  No memory allocations from the stack are lost, so
 382  *    this is always safe to call.
 383  *
 384  ***/
 385 SilcBool silc_stack_purge(SilcStack stack);
 386
 387 /****f* silcutil/SilcStackAPI/silc_stack_set_global
 388  *
 389  * SYNOPSIS
 390  *
 391  *    void silc_stack_set_global(SilcStack stack);
 392  *
 393  * DESCRIPTION
 394  *
 395  *    Sets global SilcStack `stack' that can be retrieved at any time
 396  *    by using silc_stack_get_global.  The global stack is global only
 397  *    to the current thread.  Each thread can have their own global stack.
 398  *    If each thread must have own stack this must be called in each
 399  *    thread.  If the global stack has been set already, new call will
 400  *    replace the old one.
 401  *
 402  *    This routine is provided only as a convenience function to store
 403  *    program's or thread's stack in one global place.  It is not mandatory
 404  *    to call this function in order to use SilcStack.
 405  *
 406  ***/
 407 void silc_stack_set_global(SilcStack stack);
 408
 409 /****f* silcutil/SilcStackAPI/silc_stack_get_global
 410  *
 411  * SYNOPSIS
 412  *
 413  *    SilcStack silc_stack_get_global(void);
 414  *
 415  * DESCRIPTION
 416  *
 417  *    Returns the thread's global stack that was set by calling the
 418  *    silc_stack_set_global or NULL if global stack has not been set.
 419  *
 420  ***/
 421 SilcStack silc_stack_get_global(void);
 422
 423 #include "silcstack_i.h"
 424
 425 #endif /* SILCSTACK_H */