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-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 /*--------------------------------------------------------------------*/