/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
#ifndef _WGMEMPOOL_H_
#define _WGMEMPOOL_H_

#ifdef __cplusplus
extern "C"
{
#endif


    /* 
     * mempool.c -- functions for efficient, pooled memory allocation
     *
     * THE BSD LICENSE
     * 
     * Redistribution and use in source and binary forms, with or without
     * modification, are permitted provided that the following conditions
     * are met:
     * 
     * - Redistributions of source code must retain the above copyright
     * notice, this list of conditions and the following disclaimer.
     * 
     * - Redistributions in binary form must reproduce the above copyright
     * notice, this list of conditions and the following disclaimer in the
     * documentation and/or other materials provided with the
     * distribution.
     * 
     * - Neither the name of the WiseGuys Internet B.V. nor the names of
     * its contributors may be used to endorse or promote products derived
     * from this software without specific prior written permission.
     * 
     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
     * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
     * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
     * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
     * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
     * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     *
     * DESCRIPTION
     *
     * These functions can be used to maintain a pool from which memory
     * can be claimed without performing numerous allocs. 
     *
     * A memory pool can increase time and space efficiency by factors
     * in situations where:
     *
     * - you need numerous allocations of little chunks of memory, e.g.
     *   a huge list of keywords.
     * - you need little or no deallocations: preferable just one big 
     *   dealloc at the end. 
     *
     * A memory pool is unfavorable in situations where you constantly
     * alloc and free memory. 
     *
     * NOTES
     *
     * - A memory pool consists of "blocks" of a fixed size, which are
     *   added as the need for extra memory grows. 
     * 
     * - Deallocation of the individual fragments is not possible. The
     *   pool can only be deallocated in its entirety.
     *
     */


#include "common.h"

    /* 
     * wgmempool_Init() -- intialize a memory pool
     *
     * ARGUMENTS
     *
     * - blocksize : size of blocks of which pool consists
     * - maxstrsize: 
     *            -  > 0 : the maximum size of a string that is copied 
     *               with wgmempool_strdup(). Omits the necessity of boundschecking
     *               in wgmempool_strdup(), making is slighlty faster.
     *            -  0 : causes wgmempool_strdup() to do its own boundschecking,
     *               which makes it somewhat slower.
     *
     * RETURN VALUE
     *
     * mempool handler on success, NULL on error.
     * 
     */
    extern void *wgmempool_Init(uint4 blocksize, size_t maxstrsize);


    /* 
     * wgmempool_Done() -- deallocate memory pool in its entirety
     */
    extern void wgmempool_Done(void *handle);


    /* 
     * wgmempool_Reset() -- resets a memory pool for reuse
     *
     * wgmempool_Reset() preserves already claimed memory for reuse, making
     * it more time efficient than doing a wgmempool_Done() and wgmempool_Init().
     */
    extern void wgmempool_Reset(void *handle);


    /* 
     * wgmempool_alloc() -- Allocate size bytes of memory in mempool 
     *
     * ARGUMENTS
     *
     * - size: number of bytes to claim
     *
     * RETURN VALUE
     *
     * - pointer to claimed memory on success
     * - NULL on error
     */
    extern void *wgmempool_alloc(void *handle, size_t size);


    /* 
     * wgmempool_strdup() -- Allocate and copy a string to mempool
     *
     * ARGUMENTS
     *
     * - str : null-terminated string. If maxstrsize > 0 during
     *         init, strlen(str) may not be greater than this value.
     *
     * RETURN VALUE
     *
     * - pointer to duplicated string on success
     * - NULL on error
     */
    extern char *wgmempool_strdup(void *handle, const char *str);


#ifdef __cplusplus
}
#endif


#endif

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
