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
49typedef  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.) */
54PoolAlloc* VG_(newPA) ( UWord  elemSzB,
55                        UWord  nPerPool,
56                        void*  (*alloc)(HChar*, SizeT),
57                        HChar* cc,
58                        void   (*free_fn)(void*) );
59
60
61/* Free all memory associated with a PoolAlloc. */
62extern void VG_(deletePA) ( PoolAlloc* pa);
63
64/* Allocates an element from pa. */
65extern void* VG_(allocEltPA) ( PoolAlloc* pa);
66
67/* Free element of pa. */
68extern 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.
81extern 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.
86extern UWord VG_(releasePA) ( PoolAlloc* pa);
87
88#endif   // __PUB_TOOL_POOLALLOC_
89
90/*--------------------------------------------------------------------*/
91/*--- end                                    pub_tool_poolalloc.h  ---*/
92/*--------------------------------------------------------------------*/
93