.\" -*-nroff-*- .\" .\" Manual for configurable memory management .\" .\" (c) 2000, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware .\" . .\"----- Licensing notice --------------------------------------------------- .\" .\" This file is part of the mLib utilities library. .\" .\" mLib is free software: you can redistribute it and/or modify it under .\" the terms of the GNU Library General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or (at .\" your option) any later version. .\" .\" mLib is distributed in the hope that it will be useful, but WITHOUT .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public .\" License for more details. .\" .\" You should have received a copy of the GNU Library General Public .\" License along with mLib. If not, write to the Free Software .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, .\" USA. . .\"-------------------------------------------------------------------------- .so ../defs.man \" @@@PRE@@@ . .\"-------------------------------------------------------------------------- .TH arena 3mLib "3 June 2000" "Straylight/Edgeware" "mLib utilities library" .\" @arena_global .\" @arena_stdlib . .\" @arena_fakemalloc . .\" @ALLOCV_SAFE_P .\" @NEWV_SAFE_P . .\" @A_ALLOC .\" @A_ALLOCV .\" @A_NEW .\" @A_NEWV .\" @A_REALLOC .\" @A_RENEWV .\" @A_FREE . .\" @a_alloc .\" @a_allocv .\" @a_realloc .\" @a_reallocv .\" @a_free . .\"-------------------------------------------------------------------------- .SH "NAME" arena \- control of memory allocation . .\"-------------------------------------------------------------------------- .SH "SYNOPSIS" . .nf .B "#include " .PP .ta 2n .B "typedef struct {" .B " const struct arena_ops *ops"; .B "} arena;" .PP .B "typedef struct {" .BI " void *(*alloc)(arena *" a ", size_t " sz ); .BI " void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz ); .BI " void *(*free)(arena *" a ", void *" p ); .BI " void *(*purge)(arena *" a ); .B "} arena_ops;" .PP .BI "arena *arena_global;" .BI "arena arena_stdlib;" .PP .ta \w'\fBvoid *arena_fakerealloc('u .BI "void *arena_fakerealloc(arena *" a ", void *" p , .BI " size_t " sz ", size_t " osz ); .PP .BI "int ALLOCV_SAFE_P(size_t " n ", size_t " sz ); .BI "int NEWV_SAFE_P(" type " *" p ", size_t " n ); .PP .BI "void *a_alloc(arena *" a ", size_t " sz ); .BI "void *a_allocv(arena *" a ", size_t " n ", size_t " sz ); .BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz ); .ta \w'\fBvoid a_reallocv('u .BI "void *a_reallocv(arena *" a ", void *" p , .BI " size_t " n ", size_t " on ", size_t " sz ); .BI "void a_free(arena *" a ); .PP .BI "void *A_ALLOC(arena *" a ", size_t " sz ); .BI "void *A_ALLOCV(arena *" a ", size_t " n ", size_t " sz ); .BI "void A_NEW(" type " *" p ", arena *" a ); .BI "void A_NEWV(" type " *" p ", arena *" a ", size_t " n ); .BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz ", size_t " osz ); .ta \w'\fBvoid A_REALLOCV('u .BI "void *A_REALLOCV(arena *" a ", void *" p , .BI " size_t " n ", size_t " on ", size_t " sz ); .ta \w'\fBvoid A_RENEWV('u .BI "void A_RENEWV(" type " *" q ", " type " *" p ", arena *" a , .BI " size_t " n ", size_t " on ", size_t " sz ); .BI "void A_FREE(arena *" a ); .fi . .\"-------------------------------------------------------------------------- .SH "DESCRIPTION" . An .I arena is a place from which blocks of memory may be allocated and freed. The basic .B mLib library provides a single standard arena, .BR arena_stdlib , which uses the usual .BR malloc (3) and .BR free (3) calls. The global variable .B arena_global is a pointer to a `current' arena, which is a good choice to use if you can't think of anything better. .PP The macros .BR A_ALLOC , .B A_REALLOC and .B A_FREE behave like the standard C functions .BR malloc (3), .BR realloc (3) and .BR free (3), allocating, resizing and releasing blocks from a given arena. There are function-call equivalents with lower-case names too. For a more convenient interface to memory allocation, see .BR alloc (3). .PP .B Note: The .B realloc function has an extra argument .I osz specifying the old size of the block. This is for the benefit of arena handlers which can't easily find the old block's size. .PP The macro .B ALLOCV_SAFE_P returns nonzero if the product .IR n "\ \*(mu\ " sz is representable in type .B size_t and zero otherwise; i.e., it returns true if it would be safe to try to allocate .IR n "\ \*(mu\ " sz bytes. The macro .BR A_ALLOCV allocates space for an array of .I n elements each of size .IR sz , somewhat like .BR calloc (3), except that .B A_ALLOCV does not clear the allocated memory. Likewise, the macro .B A_REALLOCV resizes the block pointed to by .IR p , which previously had space for .I on elements of size .IR sz , so that it now has enough space for .I n elements, returning the new block address. There are also function-call equivalents of these macros. .PP Finally, the macro .B A_NEW sets its argument .I p to point to a freshly allocated block of memory large enough for the type that .I p points to, or to null if allocation failed. The macro .B A_NEWV sets .I p to point to memory large enough for .I n elements, each of the type that .I p points to. The macro .B A_RENEWV sets .I q to point to memory large enough for .I n elements, each of the type that .I p points to. . .SS "Defining new arenas" An .B arena is a structure containing a single member, .BR ops , which is a pointer to a structure of type .BR arena_ops . The .B arena structure may be followed in memory by data which is used by the arena's manager to maintain its state. .PP The .B arena_ops table contains function pointers which are called to perform various memory allocation tasks: .TP .BI "void *(*alloc)(arena *" a ", size_t " sz ); Allocates a block of memory, of at least .I sz bytes in size, appropriately aligned, and returns its address. .nf .TP .BI "void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz ); .fi Resizes the block pointed to by .IR p , with .I osz interesting bytes in it, so that it is at least .I sz bytes long. You can use .B arena_fakerealloc here, to fake resizing by allocating, copying and freeing, if your arena doesn't make doing something more efficient easy. .TP .BI "void (*free)(arena *" a ", void *" p ); Frees the block pointed to by .IR p . .TP .BI "void (*purge)(arena *" a ); Frees all blocks in the arena. Used when the arena is being destroyed. .PP The behaviour of the .IR alloc , .I realloc and .I free calls with respect to null pointers and zero-sized blocks is as specified by the ANSI C standard. . .\"-------------------------------------------------------------------------- .SH "SEE ALSO" . .BR alloc (3), .BR mLib (3). . .\"-------------------------------------------------------------------------- .SH AUTHOR . Mark Wooding, . .\"----- That's all, folks --------------------------------------------------