Mon, 07 Oct 2024 20:20:21 +0200
add possibility to remove arrays of data and retrieve removed data
resolves #453
resolves #413
/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright 2021 Mike Becker, 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 * \brief Interface for memory pool implementations. * \author Mike Becker * \author Olaf Wintermann * \copyright 2-Clause BSD License */ #ifndef UCX_MEMPOOL_H #define UCX_MEMPOOL_H #include "common.h" #include "allocator.h" #ifdef __cplusplus extern "C" { #endif /** Internal structure for pooled memory. */ struct cx_mempool_memory_s; /** * The basic structure of a memory pool. * Should be the first member of an actual memory pool implementation. */ struct cx_mempool_s { /** The provided allocator. */ const CxAllocator *allocator; /** * A destructor that shall be automatically registered for newly allocated memory. * This destructor MUST NOT free the memory. */ cx_destructor_func auto_destr; /** Array of pooled memory. */ struct cx_mempool_memory_s **data; /** Number of pooled memory items. */ size_t size; /** Memory pool capacity. */ size_t capacity; }; /** * Common type for all memory pool implementations. */ typedef struct cx_mempool_s CxMempool; /** * Creates an array-based memory pool with a shared destructor function. * * This destructor MUST NOT free the memory. * * @param capacity the initial capacity of the pool * @param destr the destructor function to use for allocated memory * @return the created memory pool or \c NULL if allocation failed */ __attribute__((__warn_unused_result__)) CxMempool *cxMempoolCreate(size_t capacity, cx_destructor_func destr); /** * Creates a basic array-based memory pool. * * @param capacity the initial capacity of the pool * @return the created memory pool or \c NULL if allocation failed */ __attribute__((__warn_unused_result__)) static inline CxMempool *cxBasicMempoolCreate(size_t capacity) { return cxMempoolCreate(capacity, NULL); } /** * Destroys a memory pool and frees the managed memory. * * @param pool the memory pool to destroy */ __attribute__((__nonnull__)) void cxMempoolDestroy(CxMempool *pool); /** * Sets the destructor function for a specific allocated memory object. * * If the memory is not managed by a UCX memory pool, the behavior is undefined. * The destructor MUST NOT free the memory. * * @param memory the object allocated in the pool * @param fnc the destructor function */ __attribute__((__nonnull__)) void cxMempoolSetDestructor( void *memory, cx_destructor_func fnc ); /** * Registers foreign memory with this pool. * * The destructor, in contrast to memory allocated by the pool, MUST free the memory. * * A small portion of memory will be allocated to register the information in the pool. * If that allocation fails, this function will return non-zero. * * @param pool the pool * @param memory the object allocated in the pool * @param destr the destructor function * @return zero on success, non-zero on failure */ __attribute__((__nonnull__)) int cxMempoolRegister( CxMempool *pool, void *memory, cx_destructor_func destr ); #ifdef __cplusplus } // extern "C" #endif #endif // UCX_MEMPOOL_H