git.ozlabs.org Git - ccan/blob - ccan/alloc/alloc.h

   1 #ifndef ALLOC_H
   2 #define ALLOC_H
   3 #include <stdio.h>
   4 #include <stdbool.h>
   5
   6 /**
   7  * alloc_init - initialize a pool of memory for the allocator.
   8  * @pool: the contiguous bytes for the allocator to use
   9  * @poolsize: the size of the pool
  10  *
  11  * This stores all the setup state required to perform allocation within the
  12  * pool (there is no external state).  Any previous contents of @pool is
  13  * discarded.
  14  *
  15  * The same @pool and @poolsize arguments must be handed to the other alloc
  16  * functions after this.
  17  *
  18  * If the pool is too small for meaningful allocations, alloc_get will fail.
  19  *
  20  * Example:
  21  *      void *pool = malloc(32*1024*1024);
  22  *      if (!pool)
  23  *              err(1, "Failed to allocate 32MB");
  24  *      alloc_init(pool, 32*1024*1024);
  25  */
  26 void alloc_init(void *pool, unsigned long poolsize);
  27
  28 /**
  29  * alloc_get - allocate some memory from the pool
  30  * @pool: the contiguous bytes for the allocator to use
  31  * @poolsize: the size of the pool
  32  * @size: the size of the desired allocation
  33  * @align: the alignment of the desired allocation (0 or power of 2)
  34  *
  35  * This is "malloc" within an initialized pool.
  36  *
  37  * It will return a unique pointer within the pool (ie. between @pool
  38  * and @pool+@poolsize) which meets the alignment requirements of
  39  * @align.  Note that the alignment is relative to the start of the pool,
  40  * so of @pool is not aligned, the pointer won't be either.
  41  *
  42  * Returns NULL if there is no contiguous room.
  43  *
  44  * Example:
  45  *      #include <ccan/alignof/alignof.h>
  46  *      ...
  47  *              double *d = alloc_get(pool, 32*1024*1024,
  48  *                                    sizeof(*d), ALIGNOF(*d));
  49  *              if (!d)
  50  *                      err(1, "Failed to allocate a double");
  51  */
  52 void *alloc_get(void *pool, unsigned long poolsize,
  53                 unsigned long size, unsigned long align);
  54
  55 /**
  56  * alloc_free - free some allocated memory from the pool
  57  * @pool: the contiguous bytes for the allocator to use
  58  * @poolsize: the size of the pool
  59  * @p: the non-NULL pointer returned from alloc_get.
  60  *
  61  * This is "free" within an initialized pool.  A pointer should only be
  62  * freed once, and must be a pointer returned from a successful alloc_get()
  63  * call.
  64  *
  65  * Example:
  66  *      alloc_free(pool, 32*1024*1024, d);
  67  */
  68 void alloc_free(void *pool, unsigned long poolsize, void *free);
  69
  70 /**
  71  * alloc_size - get the actual size allocated by alloc_get
  72  * @pool: the contiguous bytes for the allocator to use
  73  * @poolsize: the size of the pool
  74  * @p: the non-NULL pointer returned from alloc_get.
  75  *
  76  * alloc_get() may overallocate, in which case you may use the extra
  77  * space exactly as if you had asked for it.
  78  *
  79  * The return value will always be at least the @size passed to alloc_get().
  80  *
  81  * Example:
  82  *      printf("Allocating a double actually got me %lu bytes\n",
  83  *              alloc_size(pool, 32*1024*1024, d));
  84  */
  85 unsigned long alloc_size(void *pool, unsigned long poolsize, void *p);
  86
  87 /**
  88  * alloc_check - check the integrity of the allocation pool
  89  * @pool: the contiguous bytes for the allocator to use
  90  * @poolsize: the size of the pool
  91  *
  92  * alloc_check() can be used for debugging suspected pool corruption.  It may
  93  * be quite slow, but provides some assistance for hard-to-find overruns or
  94  * double-frees.  Unlike the rest of the code, it will not crash on corrupted
  95  * pools.
  96  *
  97  * There is an internal function check_fail() which this calls on failure which
  98  * is useful for placing breakpoints and gaining more insight into the type
  99  * of the corruption detected.
 100  *
 101  * Example:
 102  *      #include <assert.h>
 103  *      ...
 104  *              assert(alloc_check(pool, 32*1024*1024));
 105  */
 106 bool alloc_check(void *pool, unsigned long poolsize);
 107
 108 /**
 109  * alloc_visualize - dump information about the allocation pool
 110  * @pool: the contiguous bytes for the allocator to use
 111  * @poolsize: the size of the pool
 112  *
 113  * When debugging the allocator itself, it's often useful to see how
 114  * the pool is being used.  alloc_visualize() does that, but makes
 115  * assumptions about correctness (like the rest of the code) so if you
 116  * suspect corruption call alloc_check() first.
 117  *
 118  * Example:
 119  *      d = alloc_get(pool, 32*1024*1024, sizeof(*d), ALIGNOF(*d));
 120  *      if (!d) {
 121  *              fprintf(stderr, "Allocation failed!\n");
 122  *              if (!alloc_check(pool, 32*1024*1024))
 123  *                      errx(1, "Allocation pool is corrupt");
 124  *              alloc_visualize(stderr, pool, 32*1024*1024);
 125  *              exit(1);
 126  *      }
 127  */
 128 void alloc_visualize(FILE *out, void *pool, unsigned long poolsize);
 129 #endif /* ALLOC_H */