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
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
15 * The same @pool and @poolsize arguments must be handed to the other alloc
16 * functions after this.
18 * If the pool is too small for meaningful allocations, alloc_get will fail.
21 * void *pool = malloc(32*1024*1024);
23 * err(1, "Failed to allocate 32MB");
24 * alloc_init(pool, 32*1024*1024);
26 void alloc_init(void *pool, unsigned long poolsize);
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)
35 * This is "malloc" within an initialized pool.
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.
42 * Returns NULL if there is no contiguous room.
45 * #include <ccan/alignof/alignof.h>
47 * double *d = alloc_get(pool, 32*1024*1024,
48 * sizeof(*d), ALIGNOF(*d));
50 * err(1, "Failed to allocate a double");
52 void *alloc_get(void *pool, unsigned long poolsize,
53 unsigned long size, unsigned long align);
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.
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()
66 * alloc_free(pool, 32*1024*1024, d);
68 void alloc_free(void *pool, unsigned long poolsize, void *free);
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.
76 * alloc_get() may overallocate, in which case you may use the extra
77 * space exactly as if you had asked for it.
79 * The return value will always be at least the @size passed to alloc_get().
82 * printf("Allocating a double actually got me %lu bytes\n",
83 * alloc_size(pool, 32*1024*1024, d));
85 unsigned long alloc_size(void *pool, unsigned long poolsize, void *p);
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
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
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.
102 * #include <assert.h>
104 * assert(alloc_check(pool, 32*1024*1024));
106 bool alloc_check(void *pool, unsigned long poolsize);
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
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.
119 * d = alloc_get(pool, 32*1024*1024, sizeof(*d), ALIGNOF(*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);
128 void alloc_visualize(FILE *out, void *pool, unsigned long poolsize);