include/pub_tool_poolalloc.h

   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-2012 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_GROUPALLOC_H
  32 #define __PUB_TOOL_GROUPALLOC_H
  33
  34 //--------------------------------------------------------------------
  35 // PURPOSE: Provides efficient allocation and free of elements of
  36 // the same size.
  37 // This pool allocator manages elements alloc/free by allocating
  38 // "pools" of many elements from a lower level allocator (typically
  39 // pub_tool_mallocfree.h).
  40 // Single elements can then be allocated and released from these pools.
  41 // A pool allocator is faster and has less memory overhead than
  42 // calling directly pub_tool_mallocfree.h
  43 // Note: the pools of elements are not freed, even if all the
  44 // single elements have been freed. The only way to free the underlying
  45 // pools of elements is to delete the pool allocator.
  46 //--------------------------------------------------------------------
  47
  48
  49 typedef  struct _PoolAlloc  PoolAlloc;
  50
  51 /* Create new PoolAlloc, using given allocation and free function, and
  52    for elements of the specified size.  Alloc fn must not fail (that
  53    is, if it returns it must have succeeded.) */
  54 PoolAlloc* VG_(newPA) ( UWord  elemSzB,
  55                         UWord  nPerPool,
  56                         void*  (*alloc)(const HChar*, SizeT),
  57                         const  HChar* cc,
  58                         void   (*free_fn)(void*) );
  59
  60
  61 /* Free all memory associated with a PoolAlloc. */
  62 extern void VG_(deletePA) ( PoolAlloc* pa);
  63
  64 /* Allocates an element from pa. */
  65 extern void* VG_(allocEltPA) ( PoolAlloc* pa);
  66
  67 /* Free element of pa. */
  68 extern void VG_(freeEltPA) ( PoolAlloc* pa, void* p);
  69
  70 /* A pool allocator can be shared between multiple data structures.
  71    For example, multiple OSet* can allocate/free nodes from the same
  72    pool allocator.
  73    The Pool Allocator provides support to use a ref counter
  74    to detect a pool allocator is not needed anymore.
  75    It is the caller responsibility to delete the PA if the ref counter
  76    drops to 0. In other words, this just helps the caller to manage
  77    the PA memory destruction but it does not fully manage it.
  78    Note that the usage of pool reference counting is optional. */
  79
  80 // VG_(addRefPA) indicates there is a new reference to pa.
  81 extern void VG_(addRefPA) ( PoolAlloc* pa);
  82
  83 // VG_(releasePA) decrements the pa reference count and deletes the pa if that
  84 // reference count has dropped to zero. Returns the new value of the reference
  85 // count.
  86 extern UWord VG_(releasePA) ( PoolAlloc* pa);
  87
  88 #endif   // __PUB_TOOL_POOLALLOC_
  89
  90 /*--------------------------------------------------------------------*/
  91 /*--- end                                    pub_tool_poolalloc.h  ---*/
  92 /*--------------------------------------------------------------------*/