| 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" mLib |
| 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> |