cededfbe |
1 | .\" -*-nroff-*- |
2 | .TH arena 3 "3 June 2000" mLib |
3 | .SH "NAME" |
4 | arena \- control of memory allocation |
5 | .\" @arena_global |
6 | .\" @arena_stdlib |
7 | .\" @arena_fakemalloc |
8 | .\" @a_alloc |
9 | .\" @a_realloc |
10 | .\" @a_free |
11 | .\" @A_ALLOC |
12 | .\" @A_REALLOC |
13 | .\" @A_FREE |
14 | .SH "SYNOPSIS" |
15 | .nf |
16 | .B "#include <mLib/arena.h>" |
17 | |
18 | .BI "arena *arena_global;" |
19 | .BI "arena arena_stdlib;" |
20 | |
21 | .BI "void *arena_fakerealloc(arena *" a ", void *" p ", size_t " sz ); |
22 | |
23 | .BI "void *a_alloc(arena *" a ", size_t " sz ); |
24 | .BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz ); |
25 | .BI "void a_free(arena *" a ); |
26 | |
27 | .BI "void *A_ALLOC(arena *" a ", size_t " sz ); |
28 | .BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz ); |
29 | .BI "void A_FREE(arena *" a ); |
30 | .fi |
31 | .SH "DESCRIPTION" |
32 | An |
33 | .I arena |
34 | is a place from which blocks of memory may be allocated and freed. The |
35 | basic |
36 | .B mLib |
37 | library provides a single standard arena, |
38 | .BR arena_stdlib , |
39 | which uses the usual |
40 | .BR malloc (3) |
41 | and |
42 | .BR free (3) |
43 | calls. The global variable |
44 | .B arena_global |
45 | is a pointer to a `current' arena, which is a good choice to use if |
46 | you can't think of anything better. |
47 | .PP |
48 | The macros |
49 | .BR A_ALLOC , |
50 | .B A_REALLOC |
51 | and |
52 | .B A_FREE |
53 | behave like the standard C functions |
54 | .BR malloc (3), |
55 | .BR realloc (3) |
56 | and |
57 | .BR free (3), |
58 | allocating, resizing and releasing blocks from a given arena. There are |
59 | function-call equivalents with lower-case names too. For a more |
60 | convenient interface to memory allocation, see |
61 | .BR alloc (3). |
62 | .PP |
63 | .SS "Defining new arenas" |
64 | An |
65 | .B arena |
66 | is a structure containing a single member, |
67 | .BR ops , |
68 | which is a pointer to a structure of type |
69 | .BR arena_ops . |
70 | The |
71 | .B arena |
72 | structure may be followed in memory by data which is used by the arena's |
73 | manager to maintain its state. |
74 | .PP |
75 | The |
76 | .B arena_ops |
77 | table contains function pointers which are called to perform various |
78 | memory allocation tasks: |
79 | .TP |
80 | .BI "void *(*" alloc ")(arena *" a ", size_t " sz ); |
81 | Allocates a block of memory, of at least |
82 | .I sz |
83 | bytes in size, appropriately aligned, and returns its address. |
84 | .TP |
85 | .BI "void *(*" realloc ")(arena *" a ", void *" p ", size_t " sz ); |
86 | Resizes the block pointed to by |
87 | .IR p , |
88 | so that it is at least |
89 | .I sz |
90 | bytes long. You can use |
91 | .B arena_fakerealloc |
92 | here, to fake resizing by allocating, copying and freeing, if your arena |
93 | doesn't make doing something more efficient easy. |
94 | .TP |
95 | .BI "void (*" free ")(arena *" a ", void *" p ); |
96 | Frees the block pointed to by |
97 | .IR p . |
98 | .TP |
99 | .BI "void (*" purge ")(arena *" a ); |
100 | Frees all blocks in the arena. Used when the arena is being destroyed. |
101 | .PP |
102 | The behaviour of the |
103 | .IR alloc , |
104 | .I realloc |
105 | and |
106 | .I free |
107 | calls with respect to null pointers and zero-sized blocks is as |
108 | specified by the ANSI C standard. |
109 | .SH "SEE ALSO" |
110 | .BR alloc (3), |
111 | .BR mLib (3). |
112 | .SH AUTHOR |
113 | Mark Wooding, <mdw@nsict.org> |