| 1 | .\" -*-nroff-*- |
| 2 | .de VS |
| 3 | .sp 1 |
| 4 | .RS |
| 5 | .nf |
| 6 | .ft B |
| 7 | .. |
| 8 | .de VE |
| 9 | .ft R |
| 10 | .fi |
| 11 | .RE |
| 12 | .sp 1 |
| 13 | .. |
| 14 | .TH sub 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library" |
| 15 | .SH NAME |
| 16 | sub \- efficient allocation and freeing of small blocks |
| 17 | .\" @subarena_create |
| 18 | .\" @subarena_destroy |
| 19 | .\" @subarena_alloc |
| 20 | .\" @subarena_free |
| 21 | .\" @sub_alloc |
| 22 | .\" @sub_free |
| 23 | .\" @sub_init |
| 24 | .\" |
| 25 | .\" @A_CREATE |
| 26 | .\" @A_DESTROY |
| 27 | .\" @CREATE |
| 28 | .\" @DESTROY |
| 29 | .\" |
| 30 | .SH SYNOPSIS |
| 31 | .nf |
| 32 | .B "#include <mLib/sub.h>" |
| 33 | |
| 34 | .BI "void subarena_create(subarena *" s ", arena *" a ); |
| 35 | .BI "void subarena_destroy(subarena *" s ); |
| 36 | .BI "void subarena_alloc(subarena *" s ", size_t " sz ); |
| 37 | .BI "void subarena_free(subarena *" s ", void *" p ", size_t " sz ); |
| 38 | |
| 39 | .B "void sub_init(void);" |
| 40 | .BI "void *sub_alloc(size_t " sz ); |
| 41 | .BI "void sub_free(void *" p ", size_t " sz ); |
| 42 | |
| 43 | .BI "void *A_CREATE(subarena *" s ", " type ); |
| 44 | .BI "void A_DESTROY(subarena *" s ", " type " *" p ); |
| 45 | .BI "void *CREATE(" type ); |
| 46 | .BI "void DESTROY(" type " *" p ); |
| 47 | .fi |
| 48 | .SH DESCRIPTION |
| 49 | The |
| 50 | .B subarena |
| 51 | collection of functions and macros implement an efficient allocator for |
| 52 | small blocks of known sizes, constructed from a general allocator |
| 53 | implemented by an |
| 54 | .BR arena (3). |
| 55 | Free blocks of the same size are linked together in list, making freeing |
| 56 | and allocation fast. The `free' operation requires the block size as an |
| 57 | argument, so there's no data overhead for an allocated block. The |
| 58 | system takes advantage of this by allocating big chunks from the |
| 59 | underlying arena and splitting the chunks into smaller blocks of the |
| 60 | right size, so the space and time overhead from the underlying allocator |
| 61 | is divided over many blocks. |
| 62 | .PP |
| 63 | Calling |
| 64 | .B subarena_alloc |
| 65 | allocates a block of |
| 66 | .I sz |
| 67 | bytes from the subarena |
| 68 | .IR s . |
| 69 | If there isn't enough memory to allocate the block, the |
| 70 | exception |
| 71 | .B EXC_NOMEM |
| 72 | is raised. |
| 73 | .PP |
| 74 | The |
| 75 | .B subarena_free |
| 76 | function frees a block allocated by |
| 77 | .B subarena_alloc |
| 78 | from the same subarena. You must know the size of the block in advance. |
| 79 | Note that |
| 80 | .B subarena_free |
| 81 | never gives memory back to the underlying allocator. Free sub-blocks |
| 82 | are just made available to later calls of |
| 83 | .BR subarena_alloc . |
| 84 | .PP |
| 85 | Don't try to free blocks allocated by |
| 86 | .B subarena_alloc |
| 87 | to the underlying arena's |
| 88 | .I free |
| 89 | function, or to try freeing blocks obtained directly from the arena's |
| 90 | .I alloc |
| 91 | function using |
| 92 | .BR subarena_free . |
| 93 | If you do, you'll get what you deserve. |
| 94 | .PP |
| 95 | The pair of macros |
| 96 | .B A_CREATE |
| 97 | and |
| 98 | .B A_DESTROY |
| 99 | are intended to provide a slightly more natural interface to |
| 100 | allocation. The call |
| 101 | .VS |
| 102 | mystruct *p = subarena_alloc(s, sizeof(mystruct)); |
| 103 | .VE |
| 104 | can be replaced by |
| 105 | .VS |
| 106 | mystruct p = A_CREATE(s, mystruct); |
| 107 | .VE |
| 108 | Similarly, the block can be freed by saying |
| 109 | .VS |
| 110 | A_DESTROY(s, p) |
| 111 | .VE |
| 112 | rather than the more cumbersome |
| 113 | .VS |
| 114 | subarena_free(s, p, sizeof(*p)); |
| 115 | .VE |
| 116 | There is a standard subarena |
| 117 | .B sub_global |
| 118 | which uses |
| 119 | .B arena_global |
| 120 | as its underlying allocator (obtained the first time the subarena is |
| 121 | used). The functions |
| 122 | .B sub_alloc |
| 123 | and |
| 124 | .B sub_free |
| 125 | and the macros |
| 126 | .B CREATE |
| 127 | and |
| 128 | .B DESTROY |
| 129 | use this subarena. |
| 130 | .PP |
| 131 | The function |
| 132 | .B sub_init |
| 133 | ought to be called before any of the other functions as a matter of good |
| 134 | taste, but actually the system will initialize itself the first time |
| 135 | it's used. |
| 136 | .SH "SEE ALSO" |
| 137 | .BR arena (3), |
| 138 | .BR exc (3), |
| 139 | .BR alloc (3), |
| 140 | .BR mLib (3). |
| 141 | .SH AUTHOR |
| 142 | Mark Wooding, <mdw@nsict.org> |