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 51 typedef 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. */ 57 extern 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. */ 65 extern void VG_(deletePA) ( PoolAlloc* pa); 66 67 /* Allocates an element from pa. The function never returns NULL. */ 68 extern void* VG_(allocEltPA) ( PoolAlloc* pa); 69 70 /* Free element of pa. */ 71 extern 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. 85 extern 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. 90 extern 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. 96 extern UWord VG_(sizePA) ( PoolAlloc* pa); 97 #endif // __PUB_TOOL_POOLALLOC_ 98 99 /*--------------------------------------------------------------------*/ 100 /*--- end pub_tool_poolalloc.h ---*/ 101 /*--------------------------------------------------------------------*/ 102