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