src/pool.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   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.
   6  */
   7 #ifndef INCLUDE_pool_h__
   8 #define INCLUDE_pool_h__
   9
  10 #include "common.h"
  11
  12 #include "vector.h"
  13
  14 typedef struct git_pool_page git_pool_page;
  15
  16 #ifndef GIT_DEBUG_POOL
  17 /**
  18  * Chunked allocator.
  19  *
  20  * A `git_pool` can be used when you want to cheaply allocate
  21  * multiple items of the same type and are willing to free them
  22  * all together with a single call.  The two most common cases
  23  * are a set of fixed size items (such as lots of OIDs) or a
  24  * bunch of strings.
  25  *
  26  * Internally, a `git_pool` allocates pages of memory and then
  27  * deals out blocks from the trailing unused portion of each page.
  28  * The pages guarantee that the number of actual allocations done
  29  * will be much smaller than the number of items needed.
  30  *
  31  * For examples of how to set up a `git_pool` see `git_pool_init`.
  32  */
  33 typedef struct {
  34         git_pool_page *pages; /* allocated pages */
  35         size_t item_size;  /* size of single alloc unit in bytes */
  36         size_t page_size;  /* size of page in bytes */
  37 } git_pool;
  38
  39 #define GIT_POOL_INIT { NULL, 0, 0 }
  40
  41 #else
  42
  43 /**
  44  * Debug chunked allocator.
  45  *
  46  * Acts just like `git_pool` but instead of actually pooling allocations it
  47  * passes them through to `git__malloc`. This makes it possible to easily debug
  48  * systems that use `git_pool` using valgrind.
  49  *
  50  * In order to track allocations during the lifetime of the pool we use a
  51  * `git_vector`. When the pool is deallocated everything in the vector is
  52  * freed.
  53  *
  54  * `API is exactly the same as the standard `git_pool` with one exception.
  55  * Since we aren't allocating pages to hand out in chunks we can't easily
  56  * implement `git_pool__open_pages`.
  57  */
  58 typedef struct {
  59         git_vector allocations;
  60         size_t item_size;
  61         size_t page_size;
  62 } git_pool;
  63
  64 #define GIT_POOL_INIT { GIT_VECTOR_INIT, 0, 0 }
  65
  66 #endif
  67
  68 /**
  69  * Initialize a pool.
  70  *
  71  * To allocation strings, use like this:
  72  *
  73  *     git_pool_init(&string_pool, 1);
  74  *     my_string = git_pool_strdup(&string_pool, your_string);
  75  *
  76  * To allocate items of fixed size, use like this:
  77  *
  78  *     git_pool_init(&pool, sizeof(item));
  79  *     my_item = git_pool_malloc(&pool, 1);
  80  *
  81  * Of course, you can use this in other ways, but those are the
  82  * two most common patterns.
  83  */
  84 extern int git_pool_init(git_pool *pool, size_t item_size);
  85
  86 /**
  87  * Free all items in pool
  88  */
  89 extern void git_pool_clear(git_pool *pool);
  90
  91 /**
  92  * Swap two pools with one another
  93  */
  94 extern void git_pool_swap(git_pool *a, git_pool *b);
  95
  96 /**
  97  * Allocate space for one or more items from a pool.
  98  */
  99 extern void *git_pool_malloc(git_pool *pool, size_t items);
 100 extern void *git_pool_mallocz(git_pool *pool, size_t items);
 101
 102 /**
 103  * Allocate space and duplicate string data into it.
 104  *
 105  * This is allowed only for pools with item_size == sizeof(char)
 106  */
 107 extern char *git_pool_strndup(git_pool *pool, const char *str, size_t n);
 108
 109 /**
 110  * Allocate space and duplicate a string into it.
 111  *
 112  * This is allowed only for pools with item_size == sizeof(char)
 113  */
 114 extern char *git_pool_strdup(git_pool *pool, const char *str);
 115
 116 /**
 117  * Allocate space and duplicate a string into it, NULL is no error.
 118  *
 119  * This is allowed only for pools with item_size == sizeof(char)
 120  */
 121 extern char *git_pool_strdup_safe(git_pool *pool, const char *str);
 122
 123 /**
 124  * Allocate space for the concatenation of two strings.
 125  *
 126  * This is allowed only for pools with item_size == sizeof(char)
 127  */
 128 extern char *git_pool_strcat(git_pool *pool, const char *a, const char *b);
 129
 130 /*
 131  * Misc utilities
 132  */
 133 #ifndef GIT_DEBUG_POOL
 134 extern uint32_t git_pool__open_pages(git_pool *pool);
 135 #endif
 136 extern bool git_pool__ptr_in_pool(git_pool *pool, void *ptr);
 137
 138 /**
 139  * This function is being called by our global setup routines to
 140  * initialize the system pool size.
 141  *
 142  * @return 0 on success, <0 on failure
 143  */
 144 extern int git_pool_global_init(void);
 145
 146 #endif