1 2/*--------------------------------------------------------------------*/ 3/*--- A simple pool (memory) allocator. pub_tool_poolalloc.h ---*/ 4/*--------------------------------------------------------------------*/ 5 6/* 7 This file is part of Valgrind, a dynamic binary instrumentation 8 framework. 9 10 Copyright (C) 2011-2017 OpenWorks LLP info@open-works.co.uk, 11 Philippe Waroquiers philippe.waroquiers@skynet.be 12 13 This program is free software; you can redistribute it and/or 14 modify it under the terms of the GNU General Public License as 15 published by the Free Software Foundation; either version 2 of the 16 License, or (at your option) any later version. 17 18 This program is distributed in the hope that it will be useful, but 19 WITHOUT ANY WARRANTY; without even the implied warranty of 20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 General Public License for more details. 22 23 You should have received a copy of the GNU General Public License 24 along with this program; if not, write to the Free Software 25 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 26 02111-1307, USA. 27 28 The GNU General Public License is contained in the file COPYING. 29*/ 30 31#ifndef __PUB_TOOL_POOLALLOC_H 32#define __PUB_TOOL_POOLALLOC_H 33 34#include "pub_tool_basics.h" // UWord 35 36//-------------------------------------------------------------------- 37// PURPOSE: Provides efficient allocation and free of elements of 38// the same size. 39// This pool allocator manages elements alloc/free by allocating 40// "pools" of many elements from a lower level allocator (typically 41// pub_tool_mallocfree.h). 42// Single elements can then be allocated and released from these pools. 43// A pool allocator is faster and has less memory overhead than 44// calling directly pub_tool_mallocfree.h 45// Note: the pools of elements are not freed, even if all the 46// single elements have been freed. The only way to free the underlying 47// pools of elements is to delete the pool allocator. 48//-------------------------------------------------------------------- 49 50 51typedef struct _PoolAlloc PoolAlloc; 52 53/* Create new PoolAlloc, using given allocation and free function, and 54 for elements of the specified size. alloc_fn must not return NULL (that 55 is, if it returns it must have succeeded.) 56 This function never returns NULL. */ 57extern PoolAlloc* VG_(newPA) ( UWord elemSzB, 58 UWord nPerPool, 59 Alloc_Fn_t alloc_fn, 60 const HChar* cc, 61 Free_Fn_t free_fn ); 62 63 64/* Free all memory associated with a PoolAlloc. */ 65extern void VG_(deletePA) ( PoolAlloc* pa); 66 67/* Allocates an element from pa. The function never returns NULL. */ 68extern void* VG_(allocEltPA) ( PoolAlloc* pa); 69 70/* Free element of pa. */ 71extern void VG_(freeEltPA) ( PoolAlloc* pa, void* p); 72 73/* A pool allocator can be shared between multiple data structures. 74 For example, multiple OSet* can allocate/free nodes from the same 75 pool allocator. 76 The Pool Allocator provides support to use a ref counter 77 to detect a pool allocator is not needed anymore. 78 It is the caller responsibility to call VG_(addRefPA) for 79 each new reference to a pool and VG_(releasePA) when such a reference 80 disappears. 81 VG_(releasePA) will automatically call VG_(deletePA) 82 to delete the PA when the ref counter drops to 0. */ 83 84// VG_(addRefPA) indicates there is a new reference to pa. 85extern void VG_(addRefPA) ( PoolAlloc* pa); 86 87// VG_(releasePA) decrements the pa reference count and deletes the pa if that 88// reference count has dropped to zero. Returns the new value of the reference 89// count. 90extern UWord VG_(releasePA) ( PoolAlloc* pa); 91 92// How many elements are managed by the pool 'pa'. This includes 93// the elements allocated by VG_(allocEltPA), the elements freed by 94// VG_(freeEltPA) and the elements that are in a block and have not 95// yet been allocated. 96extern UWord VG_(sizePA) ( PoolAlloc* pa); 97#endif // __PUB_TOOL_POOLALLOC_ 98 99/*--------------------------------------------------------------------*/ 100/*--- end pub_tool_poolalloc.h ---*/ 101/*--------------------------------------------------------------------*/ 102