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