commit 9ac0159d176abb7d0edd016831005206ea274ae6
parent 6673b3b3ca47c805b8a6966bd9ae6e09636a34ca
Author: gearsix <gearsix@tuta.io>
Date: Fri, 16 Sep 2022 15:46:32 +0100
minor improvements to README.md
Diffstat:
| M | README.md | | | 53 | ++++++++++++++++++++++++++++++++--------------------- |
1 file changed, 32 insertions(+), 21 deletions(-)
diff --git a/README.md b/README.md
@@ -1,50 +1,60 @@
# tralloc - track allocations
-An ANSI-C libray for tracking heap-allocated memory.
+An C libray for tracking the size of heap-allocated memory blocks.
+
+This is more of a proof-of-concept than anything and I wouldn't
+recommend using it in production. There's an accompanying article
+here:
+[Tracking Allocations in C](gearsix.net/software/tracking-allocations-in-c/)
+
## Overview
This library provides several functions that act as wrappers
-around the _stdlib_ memory allocation functions to track and
-provide information on the number of heap-allocated bytes for
-individual pointers and overall.
+around the _stdlib_ memory allocation functions to provide
+information on the number of heap-allocated bytes for individual
+pointers and overall.
It's implemented with functions the act as _stdlib_ wrappers so
that it can sit ontop of whatever _stdlib_ implementation you're
using. The downside of this is that it's unable to track any
-allocations made without these wrappers. This is acceptable since
-it's intended to be used for tracking allocations made by yourself.
+allocations made without these wrappers.
-There are also a few usability pitfalls: if you call some of the
-functions on pointers that **have not** been allocated by tralloc
-allocation functions, then it'll cause a memory error.
+There are also a few usability pitfalls:
+- If you call some of the functions on pointers that **have not**
+been allocated by tralloc allocation functions, then it'll probably
+cause a memory error.
This behaviour is consistent with stdlib though. Make sure to read
function documentation.
+- If you use a *tralloc* pointer to an address that wasn't returned
+by tralloc (either from incrementing/decrementing it), then it'll
+cause a memory error.
This was done more as a personal exercise than anything, most of the
time in C you'll track allocated memory yourself. This was just a
cool idea I got carried away with.
+
## Goals
- Track the total number of heap-allocated bytes.
-- Track number of bytes allocated for individual pointers.
-- Don't get in the way of any users.
+- Track number of bytes allocated for individual memory blocks.
+- Don't get in the way of any users, behave as regular stdlib.
+
## Guidelines
- **Do not** call `tralloc_realloc()`, `tralloc_allocsiz()` or
-`tralloc_free` on a pointer not allocated by one of the tralloc stdlib
-wrapper functions (same way you wouldn't call free on a pointer you
-didn't allocate with stdlib). Otherwise you'll probably run into a
-segfault.
-- Don't expect tralloc to track memory allocated outside of it's own
-tralloc functions.
+`tralloc_free` on an address not returned by one of the tralloc stdlib
+wrapper functions.
+- Don't expect tralloc to work on a non-tralloc pointer address.
- You should be able to use the _tralloc stdlib wrappers_ just as you
would use their stdlib counterparts without error.
- If you want to use `malloc` instead of `tr_malloc`, use a macro.
See `test.c` for an example of this.
+- It's experimental, so don't do anything silly and expect it to work.
+
## API
@@ -52,7 +62,7 @@ See `test.c` for an example of this.
size_t tralloc_siz();
-Returns the number of bytes heap-allocated by _tralloc memory allocation_
+Returns the number of bytes heap-allocated by *tralloc memory allocation*
functions.
**tralloc_limit**
@@ -77,7 +87,8 @@ Returns `n` if successful and 0 if unsuccessful.
Returns number of bytes allocated for `ptr`.
-> `ptr` **must** be a _tralloc allocated pointer_.
+> `ptr` **must** be a the address returned by a tralloc allocation.
+
### stdlib wrappers
@@ -101,13 +112,13 @@ used by functions within the library for tracking the heapsiz.
void *tralloc_realloc(void *ptr, size_t n);
-> `ptr` **must** be a pointer allocated by tralloc.
+> `ptr` **must** be a the address returned by a tralloc allocation.
**tralloc_free**
void tralloc_free(void *ptr);
-> `ptr` **must** be a pointer allocated by tralloc.
+> `ptr` **must** be a the address returned by a tralloc allocation.
## Authors
