2 * UCW Library -- Memory Pools
4 * (c) 1997--2005 Martin Mares <mj@ucw.cz>
5 * (c) 2007 Pavel Charvat <pchar@ucw.cz>
7 * This software may be freely distributed and used according to the terms
8 * of the GNU Lesser General Public License.
21 * Memory pool state (see @mp_push(), ...).
22 * You should use this one as an opaque handle only, the insides are internal.
24 struct mempool_state {
27 struct mempool_state *next;
32 * You should use this one as an opaque handle only, the insides are internal.
35 struct mempool_state state;
36 void *unused, *last_big;
37 uns chunk_size, threshold, idx;
40 struct mempool_stats { /** Mempool statistics. See @mp_stats(). **/
41 u64 total_size; /* Real allocated size in bytes */
42 uns chain_count[3]; /* Number of allocated chunks in small/big/unused chains */
43 uns chain_size[3]; /* Size of allocated chunks in small/big/unused chains */
53 * Initialize a given mempool structure.
54 * @chunk_size must be in the interval `[1, UINT_MAX / 2]`.
55 * It will allocate memory by this large chunks and take
56 * memory to satisfy requests from them.
58 * Memory pools can be treated as <<trans:respools,resources>>, see <<trans:res_mempool()>>.
60 void mp_init(struct mempool *pool, uns chunk_size);
63 * Allocate and initialize a new memory pool.
64 * See @mp_init() for @chunk_size limitations.
66 * The new mempool structure is allocated on the new mempool.
68 * Memory pools can be treated as <<trans:respools,resources>>, see <<trans:res_mempool()>>.
70 struct mempool *mp_new(uns chunk_size);
73 * Cleanup mempool initialized by mp_init or mp_new.
74 * Frees all the memory allocated by this mempool and,
75 * if created by @mp_new(), the @pool itself.
77 void mp_delete(struct mempool *pool);
80 * Frees all data on a memory pool, but leaves it working.
81 * It can keep some of the chunks allocated to serve
82 * further allocation requests. Leaves the @pool alive,
83 * even if it was created with @mp_new().
85 void mp_flush(struct mempool *pool);
88 * Compute some statistics for debug purposes.
89 * See the definition of the <<struct_mempool_stats,mempool_stats structure>>.
91 void mp_stats(struct mempool *pool, struct mempool_stats *stats);
92 u64 mp_total_size(struct mempool *pool); /** How many bytes were allocated by the pool. **/
101 /* For internal use only, do not call directly */
102 void *mp_alloc_internal(struct mempool *pool, uns size) LIKE_MALLOC;
105 * The function allocates new @size bytes on a given memory pool.
106 * If the @size is zero, the resulting pointer is undefined,
107 * but it may be safely reallocated or used as the parameter
108 * to other functions below.
110 * The resulting pointer is always aligned to a multiple of
111 * `CPU_STRUCT_ALIGN` bytes and this condition remains true also
112 * after future reallocations.
114 void *mp_alloc(struct mempool *pool, uns size);
117 * The same as @mp_alloc(), but the result may be unaligned.
119 void *mp_alloc_noalign(struct mempool *pool, uns size);
122 * The same as @mp_alloc(), but fills the newly allocated memory with zeroes.
124 void *mp_alloc_zero(struct mempool *pool, uns size);
127 * Inlined version of @mp_alloc().
129 static inline void *mp_alloc_fast(struct mempool *pool, uns size)
131 uns avail = pool->state.free[0] & ~(CPU_STRUCT_ALIGN - 1);
134 pool->state.free[0] = avail - size;
135 return (byte *)pool->state.last[0] - avail;
138 return mp_alloc_internal(pool, size);
142 * Inlined version of @mp_alloc_noalign().
144 static inline void *mp_alloc_fast_noalign(struct mempool *pool, uns size)
146 if (size <= pool->state.free[0])
148 void *ptr = (byte *)pool->state.last[0] - pool->state.free[0];
149 pool->state.free[0] -= size;
153 return mp_alloc_internal(pool, size);
161 * You do not need to know, how a buffer will need to be large,
162 * you can grow it incrementally to needed size. You can grow only
163 * one buffer at a time on a given mempool.
165 * Similar functionality is provided by <<growbuf:,growing buffes>> module.
168 /* For internal use only, do not call directly */
169 void *mp_start_internal(struct mempool *pool, uns size) LIKE_MALLOC;
170 void *mp_grow_internal(struct mempool *pool, uns size);
171 void *mp_spread_internal(struct mempool *pool, void *p, uns size);
173 static inline uns mp_idx(struct mempool *pool, void *ptr)
175 return ptr == pool->last_big;
179 * Open a new growing buffer (at least @size bytes long).
180 * If the @size is zero, the resulting pointer is undefined,
181 * but it may be safely reallocated or used as the parameter
182 * to other functions below.
184 * The resulting pointer is always aligned to a multiple of
185 * `CPU_STRUCT_ALIGN` bytes and this condition remains true also
186 * after future reallocations. There is an unaligned version as well.
188 * Keep in mind that you can't make any other pool allocations
189 * before you "close" the growing buffer with @mp_end().
191 void *mp_start(struct mempool *pool, uns size);
192 void *mp_start_noalign(struct mempool *pool, uns size);
195 * Inlined version of @mp_start().
197 static inline void *mp_start_fast(struct mempool *pool, uns size)
199 uns avail = pool->state.free[0] & ~(CPU_STRUCT_ALIGN - 1);
203 pool->state.free[0] = avail;
204 return (byte *)pool->state.last[0] - avail;
207 return mp_start_internal(pool, size);
211 * Inlined version of @mp_start_noalign().
213 static inline void *mp_start_fast_noalign(struct mempool *pool, uns size)
215 if (size <= pool->state.free[0])
218 return (byte *)pool->state.last[0] - pool->state.free[0];
221 return mp_start_internal(pool, size);
225 * Return start pointer of the growing buffer allocated by latest @mp_start() or a similar function.
227 static inline void *mp_ptr(struct mempool *pool)
229 return (byte *)pool->state.last[pool->idx] - pool->state.free[pool->idx];
233 * Return the number of bytes available for extending the growing buffer.
234 * (Before a reallocation will be needed).
236 static inline uns mp_avail(struct mempool *pool)
238 return pool->state.free[pool->idx];
242 * Grow the buffer allocated by @mp_start() to be at least @size bytes long
243 * (@size may be less than @mp_avail(), even zero). Reallocated buffer may
244 * change its starting position. The content will be unchanged to the minimum
245 * of the old and new sizes; newly allocated memory will be uninitialized.
246 * Multiple calls to mp_grow() have amortized linear cost wrt. the maximum value of @size. */
247 static inline void *mp_grow(struct mempool *pool, uns size)
249 return (size <= mp_avail(pool)) ? mp_ptr(pool) : mp_grow_internal(pool, size);
253 * Grow the buffer by at least one byte -- equivalent to <<mp_grow(),`mp_grow`>>`(@pool, @mp_avail(pool) + 1)`.
255 static inline void *mp_expand(struct mempool *pool)
257 return mp_grow_internal(pool, mp_avail(pool) + 1);
261 * Ensure that there is at least @size bytes free after @p,
262 * if not, reallocate and adjust @p.
264 static inline void *mp_spread(struct mempool *pool, void *p, uns size)
266 return (((uns)((byte *)pool->state.last[pool->idx] - (byte *)p) >= size) ? p : mp_spread_internal(pool, p, size));
270 * Close the growing buffer. The @end must point just behind the data, you want to keep
271 * allocated (so it can be in the interval `[@mp_ptr(@pool), @mp_ptr(@pool) + @mp_avail(@pool)]`).
272 * Returns a pointer to the beginning of the just closed block.
274 static inline void *mp_end(struct mempool *pool, void *end)
276 void *p = mp_ptr(pool);
277 pool->state.free[pool->idx] = (byte *)pool->state.last[pool->idx] - (byte *)end;
282 * Return size in bytes of the last allocated memory block (with @mp_alloc() or @mp_end()).
284 static inline uns mp_size(struct mempool *pool, void *ptr)
286 uns idx = mp_idx(pool, ptr);
287 return ((byte *)pool->state.last[idx] - (byte *)ptr) - pool->state.free[idx];
291 * Open the last memory block (allocated with @mp_alloc() or @mp_end())
292 * for growing and return its size in bytes. The contents and the start pointer
293 * remain unchanged. Do not forget to call @mp_end() to close it.
295 uns mp_open(struct mempool *pool, void *ptr);
298 * Inlined version of mp_open().
300 static inline uns mp_open_fast(struct mempool *pool, void *ptr)
302 pool->idx = mp_idx(pool, ptr);
303 uns size = ((byte *)pool->state.last[pool->idx] - (byte *)ptr) - pool->state.free[pool->idx];
304 pool->state.free[pool->idx] += size;
309 * Reallocate the last memory block (allocated with @mp_alloc() or @mp_end())
310 * to the new @size. Behavior is similar to @mp_grow(), but the resulting
313 void *mp_realloc(struct mempool *pool, void *ptr, uns size);
316 * The same as @mp_realloc(), but fills the additional bytes (if any) with zeroes.
318 void *mp_realloc_zero(struct mempool *pool, void *ptr, uns size);
321 * Inlined version of mp_realloc().
323 static inline void *mp_realloc_fast(struct mempool *pool, void *ptr, uns size)
325 mp_open_fast(pool, ptr);
326 ptr = mp_grow(pool, size);
327 mp_end(pool, (byte *)ptr + size);
333 * Storing and restoring state
334 * ---------------------------
336 * Mempools can remember history of what was allocated and return back
341 * Save the current state of a memory pool.
342 * Do not call this function with an opened growing buffer.
344 static inline void mp_save(struct mempool *pool, struct mempool_state *state)
346 *state = pool->state;
347 pool->state.next = state;
351 * Save the current state to a newly allocated mempool_state structure.
352 * Do not call this function with an opened growing buffer.
354 struct mempool_state *mp_push(struct mempool *pool);
357 * Restore the state saved by @mp_save() or @mp_push() and free all
358 * data allocated after that point (including the state structure itself).
359 * You can't reallocate the last memory block from the saved state.
361 void mp_restore(struct mempool *pool, struct mempool_state *state);
364 * Inlined version of @mp_restore().
366 static inline void mp_restore_fast(struct mempool *pool, struct mempool_state *state)
368 if (pool->state.last[0] != state->last[0] || pool->state.last[1] != state->last[1])
369 mp_restore(pool, state);
372 pool->state = *state;
373 pool->last_big = &pool->last_big;
378 * Restore the state saved by the last call to @mp_push().
379 * @mp_pop() and @mp_push() works as a stack so you can push more states safely.
381 void mp_pop(struct mempool *pool);
390 char *mp_strdup(struct mempool *, const char *) LIKE_MALLOC; /** Makes a copy of a string on a mempool. Returns NULL for NULL string. **/
391 void *mp_memdup(struct mempool *, const void *, uns) LIKE_MALLOC; /** Makes a copy of a memory block on a mempool. **/
393 * Concatenates all passed strings. The last parameter must be NULL.
394 * This will concatenate two strings:
396 * char *message = mp_multicat(pool, "hello ", "world", NULL);
398 char *mp_multicat(struct mempool *, ...) LIKE_MALLOC SENTINEL_CHECK;
400 * Concatenates two strings and stores result on @mp.
402 static inline char *LIKE_MALLOC mp_strcat(struct mempool *mp, const char *x, const char *y)
404 return mp_multicat(mp, x, y, NULL);
407 * Join strings and place @sep between each two neighboring.
408 * @p is the mempool to provide memory, @a is array of strings and @n
409 * tells how many there is of them.
411 char *mp_strjoin(struct mempool *p, char **a, uns n, uns sep) LIKE_MALLOC;
413 * Convert memory block to a string. Makes a copy of the given memory block
414 * in the mempool @p, adding an extra terminating zero byte at the end.
416 char *mp_str_from_mem(struct mempool *p, const void *mem, uns len) LIKE_MALLOC;
426 * printf() into a in-memory string, allocated on the memory pool.
428 char *mp_printf(struct mempool *mp, const char *fmt, ...) FORMAT_CHECK(printf,2,3) LIKE_MALLOC;
430 * Like @mp_printf(), but uses `va_list` for parameters.
432 char *mp_vprintf(struct mempool *mp, const char *fmt, va_list args) LIKE_MALLOC;
434 * Like @mp_printf(), but it appends the data at the end of string
435 * pointed to by @ptr. The string is @mp_open()ed, so you have to
436 * provide something that can be.
438 * Returns pointer to the beginning of the string (the pointer may have
439 * changed due to reallocation).
441 char *mp_printf_append(struct mempool *mp, char *ptr, const char *fmt, ...) FORMAT_CHECK(printf,3,4);
443 * Like @mp_printf_append(), but uses `va_list` for parameters.
445 char *mp_vprintf_append(struct mempool *mp, char *ptr, const char *fmt, va_list args);