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