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