alloc: first cut of new Tridge-inspired allocator
[ccan] / 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  *      ...
105  *              assert(alloc_check(pool, 32*1024*1024));
106  */
107 bool alloc_check(void *pool, unsigned long poolsize);
108
109 /**
110  * alloc_visualize - dump information about the allocation pool
111  * @pool: the contiguous bytes for the allocator to use
112  * @poolsize: the size of the pool
113  *
114  * When debugging the allocator itself, it's often useful to see how
115  * the pool is being used.  alloc_visualize() does that, but makes
116  * assumptions about correctness (like the rest of the code) so if you
117  * suspect corruption call alloc_check() first.
118  *
119  * Example:
120  *      #include <stdio.h>
121  *
122  *      double *d = alloc_get(pool, 32*1024*1024,
123  *                            sizeof(*d), ALIGNOF(*d));
124  *      if (!d) {
125  *              fprintf(stderr, "Allocation failed!\n");
126  *              if (!alloc_check(pool, 32*1024*1024))
127  *                      errx(1, "Allocation pool is corrupt");
128  *              alloc_visualize(stderr, pool, 32*1024*1024));
129  *              exit(1);
130  *      }
131  */
132 void alloc_visualize(FILE *out, void *pool, unsigned long poolsize);
133 #endif /* ALLOC_H */