chiark / gitweb /
2a36820ecfad097978bbeb58fe4587cc67d51174
[mLib] / arena.3
1 .\" -*-nroff-*-
2 .TH arena 3 "3 June 2000" "Straylight/Edgeware" "mLib utilities library"
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 ,
22 .BI "                        size_t " sz ", size_t " osz );
23
24 .BI "void *a_alloc(arena *" a ", size_t " sz );
25 .BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
26 .BI "void a_free(arena *" a );
27
28 .BI "void *A_ALLOC(arena *" a ", size_t " sz );
29 .BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
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
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
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.
93 .nf
94 .TP
95 .BI "void *(*" realloc ")(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
96 .fi
97 Resizes the block pointed to by
98 .IR p ,
99 with
100 .I osz
101 interesting bytes in it,
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@distorted.org.uk>