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