include/valgrind/pub_tool_poolalloc.h

0001
0002 /*--------------------------------------------------------------------*/
0003 /*--- A simple pool (memory) allocator.       pub_tool_poolalloc.h ---*/
0004 /*--------------------------------------------------------------------*/
0005
0006 /*
0007    This file is part of Valgrind, a dynamic binary instrumentation
0008    framework.
0009
0010    Copyright (C) 2011-2017 OpenWorks LLP info@open-works.co.uk,
0011                            Philippe Waroquiers philippe.waroquiers@skynet.be
0012
0013    This program is free software; you can redistribute it and/or
0014    modify it under the terms of the GNU General Public License as
0015    published by the Free Software Foundation; either version 2 of the
0016    License, or (at your option) any later version.
0017
0018    This program is distributed in the hope that it will be useful, but
0019    WITHOUT ANY WARRANTY; without even the implied warranty of
0020    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0021    General Public License for more details.
0022
0023    You should have received a copy of the GNU General Public License
0024    along with this program; if not, see <http://www.gnu.org/licenses/>.
0025
0026    The GNU General Public License is contained in the file COPYING.
0027 */
0028
0029 #ifndef __PUB_TOOL_POOLALLOC_H
0030 #define __PUB_TOOL_POOLALLOC_H
0031
0032 #include "pub_tool_basics.h"   // UWord
0033
0034 //--------------------------------------------------------------------
0035 // PURPOSE: Provides efficient allocation and free of elements of
0036 // the same size.
0037 // This pool allocator manages elements alloc/free by allocating
0038 // "pools" of many elements from a lower level allocator (typically
0039 // pub_tool_mallocfree.h).
0040 // Single elements can then be allocated and released from these pools.
0041 // A pool allocator is faster and has less memory overhead than
0042 // calling directly pub_tool_mallocfree.h
0043 // Note: the pools of elements are not freed, even if all the
0044 // single elements have been freed. The only way to free the underlying
0045 // pools of elements is to delete the pool allocator.
0046 //--------------------------------------------------------------------
0047
0048
0049 typedef  struct _PoolAlloc  PoolAlloc;
0050
0051 /* Create new PoolAlloc, using given allocation and free function, and
0052    for elements of the specified size.  alloc_fn must not return NULL (that
0053    is, if it returns it must have succeeded.)
0054    This function never returns NULL. */
0055 extern PoolAlloc* VG_(newPA) ( UWord  elemSzB,
0056                                UWord  nPerPool,
0057                                Alloc_Fn_t alloc_fn,
0058                                const  HChar* cc,
0059                                Free_Fn_t free_fn );
0060
0061
0062 /* Free all memory associated with a PoolAlloc. */
0063 extern void VG_(deletePA) ( PoolAlloc* pa);
0064
0065 /* Allocates an element from pa. The function never returns NULL. */
0066 extern void* VG_(allocEltPA) ( PoolAlloc* pa);
0067
0068 /* Free element of pa. */
0069 extern void VG_(freeEltPA) ( PoolAlloc* pa, void* p);
0070
0071 /* A pool allocator can be shared between multiple data structures.
0072    For example, multiple OSet* can allocate/free nodes from the same
0073    pool allocator.
0074    The Pool Allocator provides support to use a ref counter
0075    to detect a pool allocator is not needed anymore.
0076    It is the caller responsibility to call VG_(addRefPA) for
0077    each new reference to a pool and VG_(releasePA) when such a reference
0078    disappears.
0079    VG_(releasePA) will automatically call VG_(deletePA)
0080    to delete the PA when the ref counter drops to 0. */
0081
0082 // VG_(addRefPA) indicates there is a new reference to pa.
0083 extern void VG_(addRefPA) ( PoolAlloc* pa);
0084
0085 // VG_(releasePA) decrements the pa reference count and deletes the pa if that
0086 // reference count has dropped to zero. Returns the new value of the reference
0087 // count.
0088 extern UWord VG_(releasePA) ( PoolAlloc* pa);
0089
0090 // How many elements are managed by the pool 'pa'. This includes
0091 // the elements allocated by VG_(allocEltPA), the elements freed by
0092 // VG_(freeEltPA) and the elements that are in a block and have not
0093 // yet been allocated.
0094 extern UWord VG_(sizePA) ( PoolAlloc* pa);
0095 #endif   // __PUB_TOOL_POOLALLOC_
0096
0097 /*--------------------------------------------------------------------*/
0098 /*--- end                                    pub_tool_poolalloc.h  ---*/
0099 /*--------------------------------------------------------------------*/