README.md (3649B)
1 2 # tralloc - track allocations 3 4 An C libray for tracking the size of heap-allocated memory blocks. 5 6 This is more of a proof-of-concept than anything and I wouldn't 7 recommend using it in production. There's an accompanying article 8 here: 9 [Tracking Allocations in C](gearsix.net/software/tracking-allocations-in-c/) 10 11 12 ## Overview 13 14 This library provides several functions that act as wrappers 15 around the _stdlib_ memory allocation functions to provide 16 information on the number of heap-allocated bytes for individual 17 pointers and overall. 18 19 It's implemented with functions the act as _stdlib_ wrappers so 20 that it can sit ontop of whatever _stdlib_ implementation you're 21 using. The downside of this is that it's unable to track any 22 allocations made without these wrappers. 23 24 There are also a few usability pitfalls: 25 - If you call some of the functions on pointers that **have not** 26 been allocated by tralloc allocation functions, then it'll probably 27 cause a memory error. 28 This behaviour is consistent with stdlib though. Make sure to read 29 function documentation. 30 - If you use a *tralloc* pointer to an address that wasn't returned 31 by tralloc (either from incrementing/decrementing it), then it'll 32 cause a memory error. 33 34 This was done more as a personal exercise than anything, most of the 35 time in C you'll track allocated memory yourself. This was just a 36 cool idea I got carried away with. 37 38 39 ## Goals 40 41 - Track the total number of heap-allocated bytes. 42 - Track number of bytes allocated for individual memory blocks. 43 - Don't get in the way of any users, behave as regular stdlib. 44 45 46 ## Guidelines 47 48 - **Do not** call `tralloc_realloc()`, `tralloc_allocsiz()` or 49 `tralloc_free` on an address not returned by one of the tralloc stdlib 50 wrapper functions. 51 - Don't expect tralloc to work on a non-tralloc pointer address. 52 - You should be able to use the _tralloc stdlib wrappers_ just as you 53 would use their stdlib counterparts without error. 54 - If you want to use `malloc` instead of `tr_malloc`, use a macro. 55 See `test.c` for an example of this. 56 - It's experimental, so don't do anything silly and expect it to work. 57 58 59 ## API 60 61 **tralloc_siz** 62 63 size_t tralloc_siz(); 64 65 Returns the number of bytes heap-allocated by *tralloc memory allocation* 66 functions. 67 68 **tralloc_limit** 69 70 size_t tralloc_limit(); 71 72 Returns the maximum limit set on `tralloc_siz`. 73 If 0 is returned, there is no limit (returns 0 by default). 74 75 **tralloc_setlimit** 76 77 size_t tralloc_setlimit(size_t n); 78 79 Sets the maximum limit on `tralloc_siz`. 80 If this limit is reached, then tralloc alloc functions will fail and 81 return NULL. 82 Returns `n` if successful and 0 if unsuccessful. 83 84 **tralloc_allocsiz** 85 86 size_t tralloc_allocsiz(void *ptr); 87 88 Returns number of bytes allocated for `ptr`. 89 90 > `ptr` **must** be a the address returned by a tralloc allocation. 91 92 93 ### stdlib wrappers 94 95 These functions behave exactly the same and their stdlib counterparts. 96 The only difference is that they will also add the memory overhead 97 required to track the number of allocated bytes for each pointer 98 (which `sizeof(size_t)` per-pointer) and increment/decrement the 99 tracked heapsiz accordingly. 100 This overhead is stored at index [-1] of the returned pointers and 101 used by functions within the library for tracking the heapsiz. 102 103 **tralloc_malloc** 104 105 void *tralloc_malloc(size_t n); 106 107 **tralloc_calloc** 108 109 void *tralloc_calloc(size_t num, size_t n); 110 111 **tralloc_realloc** 112 113 void *tralloc_realloc(void *ptr, size_t n); 114 115 > `ptr` **must** be a the address returned by a tralloc allocation. 116 117 **tralloc_free** 118 119 void tralloc_free(void *ptr); 120 121 > `ptr` **must** be a the address returned by a tralloc allocation. 122 123 ## Authors 124 125 - gearsix 126