From 786d7213ae2c505d8b378e41c8a87e83dac06761 Mon Sep 17 00:00:00 2001 From: Ole Kristian Morud Date: Tue, 16 Jan 2024 02:33:45 +0100 Subject: [PATCH] Update README --- README.md | 43 ++++++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 27f463c..ebe749f 100644 --- a/README.md +++ b/README.md @@ -8,45 +8,58 @@ cache locality, and reduced memory fragmentation as long as individual items don't need to be deallocated. For programs that need to micro-manage individual allocations this is not an ideal solution. -Deallocating a region of memory with arenas is extremely fast, because the arena -length is just set to 0. Allocating memory is also extremely fast. -This implementation also grows the arena on demand using mmap and mprotect. +Deallocating a region of memory with arenas is extremely fast, because the +arena length is just set to 0. Allocating memory is also extremely fast. This +implementation also grows the arena on demand using mmap and mprotect. Extending the library with a new type of allocation strategy should be easy. # Reference + ## `arena_t arena_new()` Allocate a new arena. -The underlying memory is allocated with mmap. + +If `arena_new()` fails, the struct member `data` is set to NULL. This can be +checked with `arena_new_failed()` -## `void arena_delete(arena_t *a)` +## `bool arena_new_failed(arena_t *a)` -Delete memory mapped for arena. -Should only be used with arenas from arena\_new(). +Returns true if creating a new arena failed + + +## `int arena_delete(arena_t *a)` + +Delete underlying buffer of arena. Should only be used with arenas from +`arena_new()`. + +Returns 0 on success, -1 on failure ## `arena_t arena_attach(void *ptr, size_t size)` -Attach an arena to an existing memory region. -The arena will not expand the region if space is exceeded. +Attach an arena to an existing memory region. The arena will not expand if +capacity is exceeded. ## `void *arena_detatch(arena_t arena)` -Detach an arena from an existing memory region. + +Detach an arena from an existing memory region. Returns the underlying data. ## `void arena_reset(arena_t *a)` -Reset an arena. + +Resets an arena. ## `void *arena_alloc(arena_t *a, size_t len)` -Allocate memory from an arena. -Returns NULL and sets errno on failure. + +Allocate memory with an arena. Returns NULL and sets errno on failure. ## `void *arena_calloc(arena_t *a, size_t nmemb, size_t size)` -Allocate and zero memory from an arena. -Returns NULL and sets errno on failure. + +Allocate and zero memory with an arena. Returns NULL and sets errno on +failure.