| | 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 | .\" @sub_alloc |
| | 18 | .\" @sub_free |
| | 19 | .\" @sub_init |
| | 20 | .\" |
| | 21 | .\" @CREATE |
| | 22 | .\" @DESTROY |
| | 23 | .\" |
| | 24 | .SH SYNOPSIS |
| | 25 | .nf |
| | 26 | .B "#include <mLib/sub.h>" |
| | 27 | |
| | 28 | .B "void sub_init(void);" |
| | 29 | .BI "void *sub_alloc(size_t " sz ); |
| | 30 | .BI "void sub_free(void *" p ", size_t " sz ); |
| | 31 | |
| | 32 | .BI "void *CREATE(" type ); |
| | 33 | .BI "void DESTROY(" type " *" p ); |
| | 34 | .fi |
| | 35 | .SH DESCRIPTION |
| | 36 | The |
| | 37 | .B sub |
| | 38 | collection of functions and macros implement an efficient allocator for |
| | 39 | small blocks of known sizes. Free blocks of the same size are linked |
| | 40 | together in list, making freeing and allocation fast. The `free' |
| | 41 | operation requires the block size as an argument, so there's no data |
| | 42 | overhead for an allocated block. The system takes advantage of this by |
| | 43 | allocating big chunks from the underlying system (actually via |
| | 44 | .BR xmalloc (3), |
| | 45 | q.v.) and splitting the chunks into smaller blocks of the right size, so |
| | 46 | the space and time overhead from the underlying allocator is divided |
| | 47 | over many blocks. |
| | 48 | .PP |
| | 49 | Calling |
| | 50 | .B sub_alloc |
| | 51 | allocates a block of |
| | 52 | .I sz |
| | 53 | bytes. If there isn't enough memory to allocate the block, the |
| | 54 | exception |
| | 55 | .B EXC_NOMEM |
| | 56 | is raised. |
| | 57 | .PP |
| | 58 | The |
| | 59 | .B sub_free |
| | 60 | function frees a block allocated by |
| | 61 | .BR sub_alloc . |
| | 62 | You must know the size of the block in advance. Note that |
| | 63 | .B sub_free |
| | 64 | never gives memory back to the underlying allocator. Free sub-blocks |
| | 65 | are just made available to later calls of |
| | 66 | .BR sub_alloc . |
| | 67 | .PP |
| | 68 | Don't try to pass blocks allocated by |
| | 69 | .B sub_alloc |
| | 70 | to |
| | 71 | .BR free (3); |
| | 72 | similarly, don't try to pass blocks allocated by |
| | 73 | .BR xmalloc (3) |
| | 74 | or |
| | 75 | .BR malloc (3) |
| | 76 | to |
| | 77 | .BR sub_free . |
| | 78 | If you do, you'll get what you deserve. |
| | 79 | .PP |
| | 80 | The pair of macros |
| | 81 | .B CREATE |
| | 82 | and |
| | 83 | .B DESTROY |
| | 84 | are intended to provide a slightly more natural interface to |
| | 85 | allocation. The call |
| | 86 | .VS |
| | 87 | mystruct *p = sub_alloc(sizeof(mystruct)); |
| | 88 | .VE |
| | 89 | can be replaced by |
| | 90 | .VS |
| | 91 | mystruct p = CREATE(mystruct); |
| | 92 | .VE |
| | 93 | Similarly, the block can be freed by saying |
| | 94 | .VS |
| | 95 | DESTROY(p) |
| | 96 | .VE |
| | 97 | rather than the more cumbersome |
| | 98 | .VS |
| | 99 | sub_free(p, sizeof(*p)); |
| | 100 | .VE |
| | 101 | The function |
| | 102 | .B sub_init |
| | 103 | must be called before any of the other |
| | 104 | .B sub |
| | 105 | functions or macros. |
| | 106 | .SH "SEE ALSO" |
| | 107 | .BR exc (3), |
| | 108 | .BR alloc (3), |
| | 109 | .BR mLib (3). |
| | 110 | .SH AUTHOR |
| | 111 | Mark Wooding, <mdw@nsict.org> |
~mdw / mLib / blame_incremental