/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright 2016 Olaf Wintermann. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. 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.
*
* 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 HOLDER 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.
*/
/**
* @file mempool.h
*
* Memory pool implementation.
*
* @author Mike Becker
* @author Olaf Wintermann
*/
#ifndef UCX_MEMPOOL_H
#define UCX_MEMPOOL_H
#include "ucx.h"
#include <stddef.h>
#include "allocator.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* UCX mempool structure.
*/
typedef struct {
/** UcxAllocator based on this pool */
UcxAllocator *allocator;
/** List of pointers to pooled memory. */
void **data;
/** Count of pooled memory items. */
size_t ndata;
/** Memory pool size. */
size_t size;
} UcxMempool;
/** Shorthand for a new default memory pool with a capacity of 16 elements. */
#define ucx_mempool_new_default() ucx_mempool_new(16)
/**
* Creates a memory pool with the specified initial size.
*
* As the created memory pool automatically grows in size by 16 elements, when
* trying to allocate memory on a full pool, it is recommended that you use
* a multiple of 16 for the initial size.
*
* @param n initial pool size (should be a multiple of 16)
* @return a pointer to the new memory pool
*/
UcxMempool *ucx_mempool_new(size_t n);
/**
* Resizes a memory pool.
*
* @param pool the pool to resize
* @param newcap the new capacity
* @return <code>EXIT_SUCCESS</code> on success or
* <code>EXIT_FAILURE</code> on failure
*/
int ucx_mempool_chcap(UcxMempool *pool, size_t newcap);
/**
* Changes the pool size to the next smallest multiple of 16.
*
* You may use this macro, to reduce the pool size after freeing
* many pooled memory items.
*
* @param pool the pool to clamp
* @return <code>EXIT_SUCCESS</code> on success or
* <code>EXIT_FAILURE</code> on failure
*/
#define ucx_mempool_clamp(pool) ucx_mempool_chcap(pool, \
(pool->ndata & ~0xF)+0x10)
/**
* Allocates pooled memory.
*
* @param pool the memory pool
* @param n amount of memory to allocate
* @return a pointer to the allocated memory
* @see ucx_allocator_malloc()
*/
void *ucx_mempool_malloc(UcxMempool *pool, size_t n);
/**
* Allocates a pooled memory array.
*
* The content of the allocated memory is set to zero.
*
* @param pool the memory pool
* @param nelem amount of elements to allocate
* @param elsize amount of memory per element
* @return a pointer to the allocated memory
* @see ucx_allocator_calloc()
*/
void *ucx_mempool_calloc(UcxMempool *pool, size_t nelem, size_t elsize);
/**
* Reallocates pooled memory.
*
* If the memory to be reallocated is not contained by the specified pool, the
* behavior is undefined.
*
* @param pool the memory pool
* @param ptr a pointer to the memory that shall be reallocated
* @param n the new size of the memory
* @return a pointer to the new location of the memory
* @see ucx_allocator_realloc()
*/
void *ucx_mempool_realloc(UcxMempool *pool, void *ptr, size_t n);
/**
* Frees pooled memory.
*
* Before freeing the memory, the specified destructor function (if any)
* is called.
*
* If you specify memory, that is not pooled by the specified memory pool, the
* behavior is undefined.
*
* @param pool the memory pool
* @param ptr a pointer to the memory that shall be freed
* @see ucx_mempool_set_destr()
*/
void ucx_mempool_free(UcxMempool *pool, void *ptr);
/**
* Destroys a memory pool.
*
* For each element the destructor function (if any) is called and the element
* is freed.
*
* Each of the registered destructor function that has no corresponding element
* within the pool (namely those registered by ucx_mempool_reg_destr) is
* called interleaving with the element destruction, but with guarantee to the
* order in which they were registered (FIFO order).
*
*
* @param pool the mempool to destroy
*/
void ucx_mempool_destroy(UcxMempool *pool);
/**
* Sets a destructor function for the specified memory.
*
* The destructor is automatically called when the memory is freed or the
* pool is destroyed.
*
* The only requirement for the specified memory is, that it <b>MUST</b> be
* pooled memory by a UcxMempool or an element-compatible mempool. The pointer
* to the destructor function is saved in a reserved area before the actual
* memory.
*
* @param ptr pooled memory
* @param func a pointer to the destructor function
* @see ucx_mempool_free()
* @see ucx_mempool_destroy()
*/
void ucx_mempool_set_destr(void *ptr, ucx_destructor func);
/**
* Registers a destructor function for the specified (non-pooled) memory.
*
* This is useful, if you have memory that has not been allocated by a mempool,
* but shall be managed by a mempool.
*
* This function creates an entry in the specified mempool and the memory will
* therefore (logically) convert to pooled memory.
*
* @param pool the memory pool
* @param ptr data the destructor is registered for
* @param destr a pointer to the destructor function
*/
void ucx_mempool_reg_destr(UcxMempool *pool, void *ptr, ucx_destructor destr);
#ifdef __cplusplus
}
#endif
#endif /* UCX_MEMPOOL_H */