libgit2.sys.alloc source code

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 /**
8  * License: GPL-2.0(Linking Exception)
9  */
10 module libgit2.sys.alloc;
11 
12 
13 extern (C):
14 nothrow @nogc:
15 
16 /**
17  * An instance for a custom memory allocator
18  *
19  * Setting the pointers of this structure allows the developer to implement
20  * custom memory allocators. The global memory allocator can be set by using
21  * "git_libgit2_opt_t.GIT_OPT_SET_ALLOCATOR" with the `git_libgit2_opts` function. Keep in mind
22  * that all fields need to be set to a proper function.
23  */
24 struct git_allocator
25 {
26 	/**
27 	 * Allocate `n` bytes of memory
28 	 */
29 	void* function(size_t n, const (char)* file, int line) gmalloc;
30 
31 	/**
32 	 * Allocate memory for an array of `nelem` elements, where each element
33 	 * has a size of `elsize`. Returned memory shall be initialized to
34 	 * all-zeroes
35 	 */
36 	void* function(size_t nelem, size_t elsize, const (char)* file, int line) gcalloc;
37 
38 	/**
39 	 * Allocate memory for the string `str` and duplicate its contents.
40 	 */
41 	char* function(const (char)* str, const (char)* file, int line) gstrdup;
42 
43 	/**
44 	 * Equivalent to the `gstrdup` function, but only duplicating at most
45 	 * `n + 1` bytes
46 	 */
47 	char* function(const (char)* str, size_t n, const (char)* file, int line) gstrndup;
48 
49 	/**
50 	 * Equivalent to `gstrndup`, but will always duplicate exactly `n` bytes
51 	 * of `str`. Thus, out of bounds reads at `str` may happen.
52 	 */
53 	char* function(const (char)* str, size_t n, const (char)* file, int line) gsubstrdup;
54 
55 	/**
56 	 * This function shall deallocate the old object `ptr_` and return a
57 	 * pointer to a new object that has the size specified by `size`. In
58 	 * case `ptr_` is `null`, a new array shall be allocated.
59 	 */
60 	void* function(void* ptr_, size_t size, const (char)* file, int line) grealloc;
61 
62 	/**
63 	 * This function shall be equivalent to `grealloc`, but allocating
64 	 * `neleme * elsize` bytes.
65 	 */
66 	void* function(void* ptr_, size_t nelem, size_t elsize, const (char)* file, int line) greallocarray;
67 
68 	/**
69 	 * This function shall allocate a new array of `nelem` elements, where
70 	 * each element has a size of `elsize` bytes.
71 	 */
72 	void* function(size_t nelem, size_t elsize, const (char)* file, int line) gmallocarray;
73 
74 	/**
75 	 * This function shall free the memory pointed to by `ptr_`. In case
76 	 * `ptr_` is `null`, this shall be a no-op.
77 	 */
78 	void function(void* ptr_) gfree;
79 }
80 
81 /**
82  * Initialize the allocator structure to use the `stdalloc` pointer.
83  *
84  * Set up the structure so that all of its members are using the standard
85  * "stdalloc" allocator functions. The structure can then be used with
86  * `git_allocator_setup`.
87  *
88  * Params:
89  *      allocator = The allocator that is to be initialized.
90  *
91  * Returns: An error code or 0.
92  */
93 int git_stdalloc_init_allocator(.git_allocator* allocator);
94 
95 /**
96  * Initialize the allocator structure to use the `crtdbg` pointer.
97  *
98  * Set up the structure so that all of its members are using the "crtdbg"
99  * allocator functions. Note that this allocator is only available on Windows
100  * platforms and only if libgit2 is being compiled with "-DMSVC_CRTDBG".
101  *
102  * Params:
103  *      allocator = The allocator that is to be initialized.
104  *
105  * Returns: An error code or 0.
106  */
107 int git_win32_crtdbg_init_allocator(.git_allocator* allocator);