regional.h revision 368693 
1/*
2 * regional.h -- region based memory allocator.
3 *
4 * Copyright (c) 2007, NLnet Labs. All rights reserved.
5 *
6 * This software is open source.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
14 *
15 * Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
18 *
19 * Neither the name of the NLNET LABS nor the names of its contributors may
20 * be used to endorse or promote products derived from this software without
21 * specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
29 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 */
35
36/**
37 * \file
38 * Regional allocator. Allocates small portions of of larger chunks.
39 * Based on region-allocator from NSD, but rewritten to be light.
40 *
41 * Different from (nsd) region-allocator.h
42 * 	o does not have recycle bin
43 * 	o does not collect stats; just enough to answer get_mem() in use.
44 * 	o does not keep cleanup list
45 * 	o does not have function pointers to setup
46 * 	o allocs the regional struct inside the first block.
47 * 	o can take a block to create regional from.
48 * 	o blocks and large allocations are kept on singly linked lists.
49 */
50
51#ifndef UTIL_REGIONAL_H_
52#define UTIL_REGIONAL_H_
53
54/**
55 * the regional* is the first block*.
56 * every block has a ptr to the next in first bytes.
57 * and so does the regional struct, which is the first block.
58 */
59struct regional
60{
61	/**
62	 * next chunk. NULL if first chunk is the only chunk.
63	 * first inside that chunk is the char* next pointer.
64	 * When regional_free_all() has been called this value is NULL.
65	 */
66	char* next;
67	/** first large object, cast to char** to obtain next ptr */
68	char* large_list;
69	/** total large size */
70	size_t total_large;
71	/** initial chunk size */
72	size_t first_size;
73	/** number of bytes available in the current chunk. */
74	size_t available;
75	/** current chunk data position. */
76	char* data;
77	/** threshold for outside of chunk allocations */
78	size_t large_object_size;
79	/** padding for sizeof8 alignment of sizeof(struct regional)
80	 * for 32bit systems */
81	size_t padding;
82};
83
84/**
85 * Create a new regional.
86 * @return: newly allocated regional.
87 */
88struct regional* regional_create(void);
89
90/**
91 * Create a new region, with custom settings.
92 * @param size: length of first block.
93 * @return: newly allocated regional.
94 */
95struct regional* regional_create_custom(size_t size);
96
97/**
98 * Create a new region, with custom settings, that will allocate everything
99 * outside the region chunk.
100 * @param size: length of first block.
101 * @return: newly allocated regional.
102 */
103struct regional* regional_create_nochunk(size_t size);
104
105/**
106 * Free all memory associated with regional. Only keeps the first block with
107 * the regional inside it.
108 * @param r: the region.
109 */
110void regional_free_all(struct regional *r);
111
112/**
113 * Destroy regional.  All memory associated with regional is freed as if
114 * regional_free_all was called, as well as destroying the regional struct.
115 * @param r: to delete.
116 */
117void regional_destroy(struct regional *r);
118
119/**
120 * Allocate size bytes of memory inside regional.  The memory is
121 * deallocated when region_free_all is called for this region.
122 * @param r: the region.
123 * @param size: number of bytes.
124 * @return: pointer to memory allocated.
125 */
126void *regional_alloc(struct regional *r, size_t size);
127
128/**
129 * Allocate size bytes of memory inside regional and copy INIT into it.
130 * The memory is deallocated when region_free_all is called for this
131 * region.
132 * @param r: the region.
133 * @param init: to copy.
134 * @param size: number of bytes.
135 * @return: pointer to memory allocated.
136 */
137void *regional_alloc_init(struct regional* r, const void *init, size_t size);
138
139/**
140 * Allocate size bytes of memory inside regional that are initialized to
141 * 0.  The memory is deallocated when region_free_all is called for
142 * this region.
143 * @param r: the region.
144 * @param size: number of bytes.
145 * @return: pointer to memory allocated.
146 */
147void *regional_alloc_zero(struct regional *r, size_t size);
148
149/**
150 * Duplicate string and allocate the result in regional.
151 * @param r: the region.
152 * @param string: null terminated string.
153 * @return: pointer to memory allocated.
154 */
155char *regional_strdup(struct regional *r, const char *string);
156
157/** Debug print regional statistics to log */
158void regional_log_stats(struct regional *r);
159
160/** get total memory size in use by region */
161size_t regional_get_mem(struct regional* r);
162
163#endif /* UTIL_REGIONAL_H_ */
164