Revision 5cc1e1f8 lib/resource.c

View differences:

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
{

Also available in: Unified diff