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 typedef struct git_pool_page git_pool_page;
  13
  14 /**
  15  * Chunked allocator.
  16  *
  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
  21  * bunch of strings.
  22  *
  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.
  27  *
  28  * For examples of how to set up a `git_pool` see `git_pool_init`.
  29  */
  30 typedef struct {
  31         git_pool_page *pages; /* allocated pages */
  32         uint32_t item_size;  /* size of single alloc unit in bytes */
  33         uint32_t page_size;  /* size of page in bytes */
  34 } git_pool;
  35
  36 /**
  37  * Initialize a pool.
  38  *
  39  * To allocation strings, use like this:
  40  *
  41  *     git_pool_init(&string_pool, 1);
  42  *     my_string = git_pool_strdup(&string_pool, your_string);
  43  *
  44  * To allocate items of fixed size, use like this:
  45  *
  46  *     git_pool_init(&pool, sizeof(item));
  47  *     my_item = git_pool_malloc(&pool, 1);
  48  *
  49  * Of course, you can use this in other ways, but those are the
  50  * two most common patterns.
  51  */
  52 extern void git_pool_init(git_pool *pool, uint32_t item_size);
  53
  54 /**
  55  * Free all items in pool
  56  */
  57 extern void git_pool_clear(git_pool *pool);
  58
  59 /**
  60  * Swap two pools with one another
  61  */
  62 extern void git_pool_swap(git_pool *a, git_pool *b);
  63
  64 /**
  65  * Allocate space for one or more items from a pool.
  66  */
  67 extern void *git_pool_malloc(git_pool *pool, uint32_t items);
  68 extern void *git_pool_mallocz(git_pool *pool, uint32_t items);
  69
  70 /**
  71  * Allocate space and duplicate string data into it.
  72  *
  73  * This is allowed only for pools with item_size == sizeof(char)
  74  */
  75 extern char *git_pool_strndup(git_pool *pool, const char *str, size_t n);
  76
  77 /**
  78  * Allocate space and duplicate a string into it.
  79  *
  80  * This is allowed only for pools with item_size == sizeof(char)
  81  */
  82 extern char *git_pool_strdup(git_pool *pool, const char *str);
  83
  84 /**
  85  * Allocate space and duplicate a string into it, NULL is no error.
  86  *
  87  * This is allowed only for pools with item_size == sizeof(char)
  88  */
  89 extern char *git_pool_strdup_safe(git_pool *pool, const char *str);
  90
  91 /**
  92  * Allocate space for the concatenation of two strings.
  93  *
  94  * This is allowed only for pools with item_size == sizeof(char)
  95  */
  96 extern char *git_pool_strcat(git_pool *pool, const char *a, const char *b);
  97
  98 /*
  99  * Misc utilities
 100  */
 101 extern uint32_t git_pool__open_pages(git_pool *pool);
 102 extern bool git_pool__ptr_in_pool(git_pool *pool, void *ptr);
 103
 104 #endif