1 /* Licensed under LGPLv2.1+ - see LICENSE file for details */
8 * alloc_init - initialize a pool of memory for the allocator.
9 * @pool: the contiguous bytes for the allocator to use
10 * @poolsize: the size of the pool
12 * This stores all the setup state required to perform allocation within the
13 * pool (there is no external state). Any previous contents of @pool is
16 * The same @pool and @poolsize arguments must be handed to the other alloc
17 * functions after this.
19 * If the pool is too small for meaningful allocations, alloc_get will fail.
22 * void *pool = malloc(32*1024*1024);
24 * err(1, "Failed to allocate 32MB");
25 * alloc_init(pool, 32*1024*1024);
27 void alloc_init(void *pool, unsigned long poolsize);
30 * alloc_get - allocate some memory from the pool
31 * @pool: the contiguous bytes for the allocator to use
32 * @poolsize: the size of the pool
33 * @size: the size of the desired allocation
34 * @align: the alignment of the desired allocation (0 or power of 2)
36 * This is "malloc" within an initialized pool.
38 * It will return a unique pointer within the pool (ie. between @pool
39 * and @pool+@poolsize) which meets the alignment requirements of
40 * @align. Note that the alignment is relative to the start of the pool,
41 * so of @pool is not aligned, the pointer won't be either.
43 * Returns NULL if there is no contiguous room.
46 * #include <ccan/alignof/alignof.h>
48 * double *d = alloc_get(pool, 32*1024*1024,
49 * sizeof(*d), ALIGNOF(*d));
51 * err(1, "Failed to allocate a double");
53 void *alloc_get(void *pool, unsigned long poolsize,
54 unsigned long size, unsigned long align);
57 * alloc_free - free some allocated memory from the pool
58 * @pool: the contiguous bytes for the allocator to use
59 * @poolsize: the size of the pool
60 * @p: the non-NULL pointer returned from alloc_get.
62 * This is "free" within an initialized pool. A pointer should only be
63 * freed once, and must be a pointer returned from a successful alloc_get()
67 * alloc_free(pool, 32*1024*1024, d);
69 void alloc_free(void *pool, unsigned long poolsize, void *free);
72 * alloc_size - get the actual size allocated by alloc_get
73 * @pool: the contiguous bytes for the allocator to use
74 * @poolsize: the size of the pool
75 * @p: the non-NULL pointer returned from alloc_get.
77 * alloc_get() may overallocate, in which case you may use the extra
78 * space exactly as if you had asked for it.
80 * The return value will always be at least the @size passed to alloc_get().
83 * printf("Allocating a double actually got me %lu bytes\n",
84 * alloc_size(pool, 32*1024*1024, d));
86 unsigned long alloc_size(void *pool, unsigned long poolsize, void *p);
89 * alloc_check - check the integrity of the allocation pool
90 * @pool: the contiguous bytes for the allocator to use
91 * @poolsize: the size of the pool
93 * alloc_check() can be used for debugging suspected pool corruption. It may
94 * be quite slow, but provides some assistance for hard-to-find overruns or
95 * double-frees. Unlike the rest of the code, it will not crash on corrupted
98 * There is an internal function check_fail() which this calls on failure which
99 * is useful for placing breakpoints and gaining more insight into the type
100 * of the corruption detected.
103 * #include <assert.h>
105 * assert(alloc_check(pool, 32*1024*1024));
107 bool alloc_check(void *pool, unsigned long poolsize);
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
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.
120 * d = alloc_get(pool, 32*1024*1024, sizeof(*d), ALIGNOF(*d));
122 * fprintf(stderr, "Allocation failed!\n");
123 * if (!alloc_check(pool, 32*1024*1024))
124 * errx(1, "Allocation pool is corrupt");
125 * alloc_visualize(stderr, pool, 32*1024*1024);
129 void alloc_visualize(FILE *out, void *pool, unsigned long poolsize);