2 * Copyright (C) the libgit2 contributors. All rights reserved.
4 * This file is part of libgit2, distributed under the GNU GPL v2 with
5 * a Linking Exception. For full terms see the included COPYING file.
7 #ifndef INCLUDE_pool_h__
8 #define INCLUDE_pool_h__
12 typedef struct git_pool_page git_pool_page
;
17 * A `git_pool` can be used when you want to cheaply allocate
18 * multiple items of the same type and are willing to free them
19 * all together with a single call. The two most common cases
20 * are a set of fixed size items (such as lots of OIDs) or a
23 * Internally, a `git_pool` allocates pages of memory and then
24 * deals out blocks from the trailing unused portion of each page.
25 * The pages guarantee that the number of actual allocations done
26 * will be much smaller than the number of items needed.
28 * For examples of how to set up a `git_pool` see `git_pool_init`.
31 git_pool_page
*open
; /* pages with space left */
32 git_pool_page
*full
; /* pages with no space left */
33 void *free_list
; /* optional: list of freed blocks */
34 uint32_t item_size
; /* size of single alloc unit in bytes */
35 uint32_t page_size
; /* size of page in bytes */
37 unsigned has_string_alloc
: 1; /* was the strdup function used */
38 unsigned has_multi_item_alloc
: 1; /* was items ever > 1 in malloc */
39 unsigned has_large_page_alloc
: 1; /* are any pages > page_size */
42 #define GIT_POOL_INIT_STRINGPOOL { 0, 0, 0, 1, 4000, 0, 0, 0, 0 }
47 * To allocation strings, use like this:
49 * git_pool_init(&string_pool, 1, 0);
50 * my_string = git_pool_strdup(&string_pool, your_string);
52 * To allocate items of fixed size, use like this:
54 * git_pool_init(&pool, sizeof(item), 0);
55 * my_item = git_pool_malloc(&pool, 1);
57 * Of course, you can use this in other ways, but those are the
58 * two most common patterns.
60 extern int git_pool_init(
61 git_pool
*pool
, uint32_t item_size
, uint32_t items_per_page
);
64 * Free all items in pool
66 extern void git_pool_clear(git_pool
*pool
);
69 * Swap two pools with one another
71 extern void git_pool_swap(git_pool
*a
, git_pool
*b
);
74 * Allocate space for one or more items from a pool.
76 extern void *git_pool_malloc(git_pool
*pool
, uint32_t items
);
79 * Allocate space and zero it out.
81 GIT_INLINE(void *) git_pool_mallocz(git_pool
*pool
, uint32_t items
)
83 void *ptr
= git_pool_malloc(pool
, items
);
85 memset(ptr
, 0, (size_t)items
* (size_t)pool
->item_size
);
90 * Allocate space and duplicate string data into it.
92 * This is allowed only for pools with item_size == sizeof(char)
94 extern char *git_pool_strndup(git_pool
*pool
, const char *str
, size_t n
);
97 * Allocate space and duplicate a string into it.
99 * This is allowed only for pools with item_size == sizeof(char)
101 extern char *git_pool_strdup(git_pool
*pool
, const char *str
);
104 * Allocate space and duplicate a string into it, NULL is no error.
106 * This is allowed only for pools with item_size == sizeof(char)
108 extern char *git_pool_strdup_safe(git_pool
*pool
, const char *str
);
111 * Allocate space for the concatenation of two strings.
113 * This is allowed only for pools with item_size == sizeof(char)
115 extern char *git_pool_strcat(git_pool
*pool
, const char *a
, const char *b
);
118 * Push a block back onto the free list for the pool.
120 * This is allowed only if the item_size is >= sizeof(void*).
122 * In some cases, it is helpful to "release" an allocated block
123 * for reuse. Pools don't support a general purpose free, but
124 * they will keep a simple free blocks linked list provided the
125 * native block size is large enough to hold a void pointer
127 extern void git_pool_free(git_pool
*pool
, void *ptr
);
130 * Push an array of pool allocated blocks efficiently onto the free list.
132 * This has the same constraints as `git_pool_free()` above.
134 extern void git_pool_free_array(git_pool
*pool
, size_t count
, void **ptrs
);
140 extern uint32_t git_pool__open_pages(git_pool
*pool
);
142 extern uint32_t git_pool__full_pages(git_pool
*pool
);
144 extern bool git_pool__ptr_in_pool(git_pool
*pool
, void *ptr
);
146 extern uint32_t git_pool__suggest_items_per_page(uint32_t item_size
);