Revision 5cc1e1f8

View differences:

lib/Doc
2 2
S ip.c ipv4.c ipv6.c
3 3
S lists.c
4 4
S checksum.c bitops.c patmatch.c printf.c xmalloc.c
5
H Resources
5
D resource.sgml
6 6
S resource.c
7 7
S mempool.c
8 8
S slab.c
lib/mempool.c
1 1
/*
2 2
 *	BIRD Resource Manager -- Memory Pools
3 3
 *
4
 *	(c) 1998--1999 Martin Mares <mj@ucw.cz>
4
 *	(c) 1998--2000 Martin Mares <mj@ucw.cz>
5 5
 *
6 6
 *	Can be freely distributed and used under the terms of the GNU GPL.
7 7
 */
8 8

  
9
/**
10
 * DOC: Linear memory pools
11
 *
12
 * Linear memory pools are collections of memory blocks which
13
 * support very fast allocation of new blocks, but are able to free only
14
 * the whole collection at once.
15
 *
16
 * Example: Each configuration is described by a complex system of structures,
17
 * linked lists and function trees which are all allocated from a single linear
18
 * pool, thus they can be freed at once when the configuration is no longer used.
19
 */
20

  
9 21
#include <stdlib.h>
10 22

  
11 23
#include "nest/bird.h"
......
38 50
  lp_lookup
39 51
};
40 52

  
53
/**
54
 * lp_new - create a new linear memory pool
55
 * @p: pool
56
 * @blk: block size
57
 *
58
 * lp_new() creates a new linear memory pool resource inside the pool @p.
59
 * The linear pool consists of a list of memory chunks of size at least
60
 * @blk.
61
 */
41 62
linpool
42 63
*lp_new(pool *p, unsigned blk)
43 64
{
......
52 73
  return m;
53 74
}
54 75

  
76
/**
77
 * lp_alloc - allocate memory from a &linpool
78
 * @m: linear memory pool
79
 * @size: amount of memory
80
 *
81
 * lp_alloc() allocates @size bytes of memory from a &linpool @m
82
 * and it returns a pointer to the allocated memory.
83
 *
84
 * It works by trying to find free space in the last memory chunk
85
 * associated with the &linpool and creating a new chunk of the standard
86
 * size (as specified during lp_new()) if the free space is too small
87
 * to satisfy the allocation. If @size is too large to fit in a standard
88
 * size chunk, an "overflow" chunk is created for it instead.
89
 */
55 90
void *
56 91
lp_alloc(linpool *m, unsigned size)
57 92
{
......
100 135
    }
101 136
}
102 137

  
138
/**
139
 * lp_allocu - allocate unaligned memory from a &linpool
140
 * @m: linear memory pool
141
 * @size: amount of memory
142
 *
143
 * lp_allocu() allocates @size bytes of memory from a &linpool @m
144
 * and it returns a pointer to the allocated memory. It doesn't
145
 * attempt to align the memory block, giving a very efficient way
146
 * how to allocate strings without any space overhead.
147
 */
103 148
void *
104 149
lp_allocu(linpool *m, unsigned size)
105 150
{
......
114 159
  return lp_alloc(m, size);
115 160
}
116 161

  
162
/**
163
 * lp_allocz - allocate cleared memory from a &linpool
164
 * @m: linear memory pool
165
 * @size: amount of memory
166
 *
167
 * This function is identical to lp_alloc() except that it
168
 * clears the allocated memory block.
169
 */
117 170
void *
118 171
lp_allocz(linpool *m, unsigned size)
119 172
{
......
123 176
  return z;
124 177
}
125 178

  
179
/**
180
 * lp_flush - flush a linear memory pool
181
 * @m: linear memory pool
182
 *
183
 * This function frees the whole contents of the given &linpool @m,
184
 * but leaves the pool itself.
185
 */
126 186
void
127 187
lp_flush(linpool *m)
128 188
{
lib/resource.c
1 1
/*
2 2
 *	BIRD Resource Manager
3 3
 *
4
 *	(c) 1998 Martin Mares <mj@ucw.cz>
4
 *	(c) 1998--2000 Martin Mares <mj@ucw.cz>
5 5
 *
6 6
 *	Can be freely distributed and used under the terms of the GNU GPL.
7 7
 */
......
13 13
#include "lib/resource.h"
14 14
#include "lib/string.h"
15 15

  
16
/**
17
 * DOC: Resource pools
18
 *
19
 * Resource pools (&pool) are just containers holding a list of
20
 * other resources. Freeing a pool causes all the listed resources
21
 * to be freed as well. Each existing &resource is linked to some pool
22
 * except for a root pool which isn't linked anywhere, so all the
23
 * resources form a tree structure with internal nodes corresponding
24
 * to pools and leaves being the other resources.
25
 *
26
 * Example: Almost all modules of BIRD have their private pool which
27
 * is freed upon shutdown of the module.
28
 */
29

  
16 30
struct pool {
17 31
  resource r;
18 32
  list inside;
......
35 49

  
36 50
static int indent;
37 51

  
52
/**
53
 * rp_new - create a resource pool
54
 * @p: parent pool
55
 * @name: pool name (to be included in debugging dumps)
56
 *
57
 * rp_new() creates a new resource pool inside the specified
58
 * parent pool.
59
 */
38 60
pool *
39 61
rp_new(pool *p, char *name)
40 62
{
......
84 106
  return NULL;
85 107
}
86 108

  
109
/**
110
 * rfree - free a resource
111
 * @res: resource
112
 *
113
 * rfree() frees the given resource and all information associated
114
 * with it. In case it's a resource pool, it also frees all the objects
115
 * living inside the pool.
116
 *
117
 * It works by calling a class-specific freeing function.
118
 */
87 119
void
88 120
rfree(void *res)
89 121
{
......
98 130
    }
99 131
}
100 132

  
133
/**
134
 * rdump - dump a resource
135
 * @res: resource
136
 *
137
 * This function prints out all available information about the given
138
 * resource to the debugging output.
139
 *
140
 * It works by calling a class-specific dump function.
141
 */
101 142
void
102 143
rdump(void *res)
103 144
{
......
115 156
    debug("NULL\n");
116 157
}
117 158

  
159
/**
160
 * ralloc - create a resource
161
 * @p: pool to create the resource in
162
 * @c: class of the new resource
163
 *
164
 * This function is called by the resource classes to create a new
165
 * resource of the specified class and link it to the given pool.
166
 * Size of the resource structure is taken from the @size field
167
 * of the &resclass.
168
 */
118 169
void *
119 170
ralloc(pool *p, struct resclass *c)
120 171
{
......
125 176
  return r;
126 177
}
127 178

  
179
/**
180
 * rlookup - look up a memory location
181
 * @a: memory address
182
 *
183
 * This function examines all existing resources to see whether
184
 * the address @a is inside any resource. It's used for debugging
185
 * purposes only.
186
 *
187
 * It works by calling a class-specific lookup function for each
188
 * resource.
189
 */
128 190
void
129 191
rlookup(unsigned long a)
130 192
{
......
137 199
    debug("Not found.\n");
138 200
}
139 201

  
202
/**
203
 * resource_init - initialize the resource manager
204
 *
205
 * This function is called during BIRD startup. It initializes
206
 * all data structures of the resource manager and creates the
207
 * root pool.
208
 */
140 209
void
141 210
resource_init(void)
142 211
{
......
145 214
  init_list(&root_pool.inside);
146 215
}
147 216

  
148
/*
149
 *	Memory blocks.
217
/**
218
 * DOC: Memory blocks
219
 *
220
 * Memory blocks are pieces of contiguous allocated memory.
221
 * They are a bit non-standard since they are represented not by a pointer
222
 * to &resource, but by a void pointer to the start of data of the
223
 * memory block. All memory block functions know how to locate the header
224
 * given the data pointer.
225
 *
226
 * Example: All "unique" data structures such as hash tables are allocated
227
 * as memory blocks.
150 228
 */
151 229

  
152 230
struct mblock {
......
184 262
  mbl_lookup
185 263
};
186 264

  
265
/**
266
 * mb_alloc - allocate a memory block
267
 * @p: pool
268
 * @size: size of the block
269
 *
270
 * mb_alloc() allocates memory of a given size and creates
271
 * a memory block resource representing this memory chunk
272
 * in the pool @p.
273
 *
274
 * Please note that mb_alloc() returns a pointer to the memory
275
 * chunk, not to the resource, hence you have to free it using
276
 * mb_free(), not rfree().
277
 */
187 278
void *
188 279
mb_alloc(pool *p, unsigned size)
189 280
{
......
195 286
  return b->data;
196 287
}
197 288

  
289
/**
290
 * mb_allocz - allocate and clear a memory block
291
 * @p: pool
292
 * @size: size of the block
293
 *
294
 * mb_allocz() allocates memory of a given size, initializes it to
295
 * zeroes and creates a memory block resource representing this memory
296
 * chunk in the pool @p.
297
 *
298
 * Please note that mb_alloc() returns a pointer to the memory
299
 * chunk, not to the resource, hence you have to free it using
300
 * mb_free(), not rfree().
301
 */
198 302
void *
199 303
mb_allocz(pool *p, unsigned size)
200 304
{
......
203 307
  return x;
204 308
}
205 309

  
310
/**
311
 * mb_free - free a memory block
312
 * @m: memory block
313
 *
314
 * mb_free() frees all memory associated with the block @m.
315
 */
206 316
void
207 317
mb_free(void *m)
208 318
{
lib/resource.sgml
1
<!--
2
	BIRD Programmer's Guide: Resources
3

  
4
	(c) 2000 Martin Mares <mj@ucw.cz>
5
-->
6

  
7
<chapt>Resources
8

  
9
<sect>Introduction
10

  
11
<p>Most large software projects implemented in classical procedural
12
programming languages usually end up with lots of code taking care
13
of resource allocation and deallocation. Bugs in such code are often
14
very difficult to find, because they cause only `resource leakage',
15
that is keeping a lot of memory and other resources which nobody
16
references to.
17

  
18
<p>We've tried to solve this problem by employing a resource tracking
19
system which keeps track of all the resources allocated by all the
20
modules of BIRD, deallocates everything automatically when a module
21
shuts down and it's is able to print out the list of resources and
22
the corresponding modules they are allocated by.
23

  
24
<p>Each allocated resource (and from now we'll speak about allocated
25
resources only) is represented by a structure starting with a standard
26
header (struct <struct/resource/) consisting of a list node (resources are
27
often linked to various lists) and a pointer to <struct/resclass/ -- a resource
28
class structure pointing to functions implementing generic resource
29
operations (such as freeing of the resource) for the particular resource
30
type.
31

  
32
<p>There exist the following types of resources:
33

  
34
<itemize>
35
<item><it/Resource pools/ (<struct/pool/)
36
<item><it/Memory blocks/
37
<item><it/Linear memory pools/ (<struct/linpool/)
38
<item><it/Slabs/ (<struct/slab/)
39
<item><it/Sockets/ (<struct/socket/) 
40
<item><it/Events/ (<struct/event/) 
41
<!--
42
 are there to keep track of deferred execution.
43
	Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller
44
	parts, so that no module can monopolize the CPU. To split such a task, just create
45
	an <struct/event/ resource, point it to the function you want to have called and call <func/ev_schedule()/
46
	to ask the core to run the event when nothing more important will require attention.
47
	The actual implementation is system dependent.
48
-->
49
<item><it/Timers/ (<struct/timer/) 
50
</itemize>
lib/slab.c
8 8
 *	Can be freely distributed and used under the terms of the GNU GPL.
9 9
 */
10 10

  
11
/**
12
 * DOC: Slabs
13
 *
14
 * Slabs are collections of memory blocks of a fixed size.
15
 * They support very fast allocation and freeing of such blocks, prevent memory
16
 * fragmentation and optimize L2 cache usage. Slabs have been invented by Jeff Bonwick
17
 * and published in USENIX proceedings as `The Slab Allocator: An Object-Caching Kernel
18
 * Memory Allocator'. Our implementation follows this article except that we don't use
19
 * constructors and destructors.
20
 *
21
 * When the |DEBUGGING| switch is turned on, we automatically fill all
22
 * newly allocated and freed blocks with a special patterns to make detection
23
 * of use of uninitialized or already freed memory easier.
24
 *
25
 * Example: Nodes of a FIB are allocated from a Slab.
26
 */
27

  
11 28
#include <stdlib.h>
12 29

  
13 30
#include "nest/bird.h"
......
139 156
  int x[0];
140 157
};
141 158

  
159
/**
160
 * sl_new - create a new Slab
161
 * @p: resource pool
162
 * @size: block size
163
 *
164
 * This function creates a new Slab resource from which
165
 * objects of size @size can be allocated.
166
 */
142 167
slab *
143 168
sl_new(pool *p, unsigned size)
144 169
{
......
183 208
  return h;
184 209
}
185 210

  
211
/**
212
 * sl_alloc - allocate an object from Slab
213
 * @s: slab
214
 *
215
 * sl_alloc() allocates space for a single object from the
216
 * Slab and returns a pointer to the object.
217
 */
186 218
void *
187 219
sl_alloc(slab *s)
188 220
{
......
223 255
  goto okay;
224 256
}
225 257

  
258
/**
259
 * sl_free - return a free object back to a Slab
260
 * @s: slab
261
 * @oo: object returned by sl_alloc()
262
 *
263
 * This function frees memory associated with the object @oo
264
 * and returns it back to the Slab @s.
265
 */
226 266
void
227 267
sl_free(slab *s, void *oo)
228 268
{

Also available in: Unified diff