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