chiark - git - mdw - mLib/blob - man/sub.3

   1 .\" -*-nroff-*-
   2 .de VS
   3 .sp 1
   4 .RS 5
   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 cubersome
  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>