Pool allocator

docs/memory.md

@@ -2,7 +2,7 @@
 
 Custom allocators and memory functions
 
-# Arena Allocator
+## Arena Allocator
 
 A simple arena-style allocator
 
@@ -11,7 +11,7 @@ A simple arena-style allocator
 ### ArenaAllocator
 
 Represents an arena allocator. `ArenaAllocator` holds its own buffer, but managing its size is left to the user. Like
-most structs in `libflint`, it must be malloced first before being passed to `arena_init()`.
+most structs in `libflint`, it must be malloc'd first before being passed to `arena_init()`.
 
 ```c
 typedef struct {
@@ -96,4 +96,99 @@ Convenience macro for getting the size of the arena's buffer
 
 ```c
 #define arena_sz(a) (a)->buf_sz
+```
+
+## Pool Allocator
+
+A pool-based allocator for chunks of the same size. Useful for quickly allocating and using memory of the same size
+without worrying about order; most operations are `O(1)`
+
+## Structs
+
+### PoolAllocator
+
+Represents a pool allocator. `PoolAllocator` holds its own buffer, but managing its size is left to the user. Like
+most structs in `libflint`, it must be malloc'd first before being passed to `pool_init()`.
+
+```c
+typedef struct {
+	unsigned char *buf;
+    size_t buf_sz;
+    size_t chunk_size;
+
+    List *free_list;
+} PoolAllocator;
+```
+
+## Functions
+
+### pool_init
+
+Initializes the `PoolAllocator`. The struct must first be created by the user using `malloc()`, see the example below.
+
+- `buf_sz`: Size of the underlying buffer in bytes
+- `chunk_sz`: Size of each chunk in bytes
+- `chunk_align`: The alignment of the chunks. The`LF_DEFAULT_ALIGNMENT` macro is available as a good default for basic types
+
+```c
+void pool_init(PoolAllocator *allocator, size_t buf_sz, size_t chunk_sz, size_t chunk_align);
+
+/* Usage */
+PoolAllocator *pool = malloc(sizeof(PoolAllocator));
+pool_init(pool, 64, 16, LF_DEFAULT_ALIGNMENT);
+```
+
+### pool_free
+
+Return a single chunk back to the pool. `ptr` is a pointer to the allocated chunk.
+
+```c
+void pool_free(PoolAllocator *allocator, void *ptr);
+```
+
+### pool_free_all
+
+Returns all chunks back to the pool. Any pointers received before this call are now invalid and must be reasigned with 
+`pool_alloc` or set to `NULL`.
+
+```c
+void pool_free_all(PoolAllocator *allocator);
+```
+
+### pool_alloc
+
+Allocate a chunk from the pool. Returns `NULL` on failure.
+
+```c
+void *pool_alloc(PoolAllocator *allocator);
+```
+
+### pool_destroy
+
+Destroys the underlying buffer and `List` in `allocator`, then frees it. User is responsible for setting `allocator` to
+`NULL` afterwards.
+
+```c
+void pool_destroy(PoolAllocator *allocator);
+```
+
+## Macros
+
+### pool_count_available
+
+Returns the amount of chunks left available in the pool
+
+```c
+#define pool_count_available(x) (x)->free_list->size
+```
+
+### LF_DEFAULT_ALIGNMENT
+
+The default alignment for allocators. Use this as a simple default (defaults to 16 bytes on amd64 systems) when storing
+basic types
+
+```c
+#ifndef DEFAULT_ALIGNMENT
+#define LF_DEFAULT_ALIGNMENT (2*sizeof(void*))
+#endif // DEFAULT_ALIGNMENT
 ```