Add manuals for the arena allocation functions

5 files changed, 177 insertions, 0 deletions

diff --git a/man/arena_alloc.3 b/man/arena_alloc.3
new file mode 100644
index 0000000..1814af1
--- /dev/null
+++ b/man/arena_alloc.3
@@ -0,0 +1,173 @@
+.Dd 27 April 2024
+.Dt ARENA_ALLOC 3
+.Os MLib
+.Sh NAME
+.Nm arena_alloc ,
+.Nm arena_free ,
+.Nm arena_new ,
+.Nm arena_zero ,
+.Nm mkarena
+.Nd arena allocator functions
+.Sh LIBRARY
+.Lb mlib
+.Sh SYNOPSIS
+.In alloc.h
+.Fd #define MLIB_ARENA_BLKSIZE 8192
+.Ft arena
+.Fn mkarena "size_t n"
+.Ft "void *"
+.Fn arena_alloc "arena *a" "size_t n" "size_t m" "size_t align"
+.Ft "T *"
+.Fn arena_new "arena *a" "type T" "size_t n"
+.Ft void
+.Fn arena_zero "arena *a"
+.Ft void
+.Fn arena_free "arena *a"
+.Sh DESCRIPTION
+The functions and macros defined in this manual implement a basic arena
+allocator.
+An arena object represents an instance of an arena allocator.
+Unlike typical dynamic memory allocation via functions such as
+.Fn malloc ,
+when an arena is freed, all allocations made using that arena are freed
+in one go.
+This allows for the simplification of lifetimes and memory management.
+As arena allocators allocate memory linearly,
+they can often also have various performance benefits over allocations
+made using allocators such as
+.Fn malloc .
+.Pp
+The
+.Fn mkarena
+function returns a new arena with a default blocksize of
+.Fa n .
+If
+.Fa n
+is 0, then
+.Dv MLIB_ARENA_BLKSIZE is used instead.
+.Pp
+The
+.Fn arena_alloc
+function allocates memory for
+.Fa n
+elements of size
+.Fa m
+in the arena pointed to by
+.Fa a
+with the alignment
+.Fa align .
+A pointer to the newly allocated memory is returned, or
+.Dv nullptr
+on error.
+In most cases it is preferable to use the
+.Fn arena_new
+macro instead of this function.
+The behavior of
+.Fn arena_alloc
+is undefined if
+.Fa align
+is not a power of 2
+.Pq this includes 0, which is not a power of 2 .
+.Pp
+The
+.Fn arena_new
+macro allocates memory for
+.Fa n
+elements of type
+.Fa T
+in the arena pointed to by
+.Fa a .
+Allocations are aligned to
+.Ql alignof(T)
+bytes.
+A pointer to the newly allocated memory is returned, or
+.Dv nullptr
+on error.
+This macro is equivalent to the following invocation of
+.Fn arena_alloc :
+.Bd -literal -offset indent
+(T *)arena_alloc(a, n, sizeof(T), alignof(T))
+.Ed
+.Pp
+The
+.Fn arena_free
+function deallocates all memory associated with the arena pointed to by
+.Fa a .
+After an arena has been freed you may safely continue to allocate memory
+with it, however you may prefer to use
+.Fn arena_zero
+in such a situation.
+.Pp
+The
+.Fn arena_zero
+function resets the state of the arena pointed to by
+.Fa a .
+This allows you to reuse the memory that has already been allocated by
+the given arena for new allocations,
+which may improve the performance of your application.
+Note that after zeroing an arena, any prior allocations made with the
+arena must be considered garbage.
+.Pp
+If you wish to configure the default blocksize of new arena allocators
+created via
+.Fn mkarena ,
+you may define
+.Dv MLIB_ARENA_BLKSIZE
+to a constant value of type
+.Vt size_t
+before including
+.In alloc.h .
+.Sh RETURN VALUES
+The
+.Fn mkarena
+function returns a new arena allocator with a given blocksize or
+.Dv MLIB_ARENA_BLKSIZE
+if zero.
+.Pp
+The
+.Fn arena_alloc
+function and
+.Fn arena_new
+macro return a pointer to the newly allocated buffer if successful;
+otherwise the value
+.Dv nullptr
+is returned and the global variable
+.Va errno
+is set to indicate the error.
+.Sh EXAMPLES
+The following example creates a new arena allocator,
+allocates two integer arrays,
+and then frees the arena.
+.Bd -literal -offset indent
+#define NUM_ELEMS 16
+
+arena a = mkarena(0);
+
+int *xs = arena_new(&a, int, NUM_ELEMS);
+int *ys = arena_new(&a, int, NUM_ELEMS);
+
+for (int i = 0; i < NUM_ELEMS; i++)
+	xs[i] = i;
+for (int i = 0; i < NUM_ELEMS; i++)
+	ys[i] = xs[i] * xs[i];
+
+arena_free(&a);
+.Ed
+.Sh ERRORS
+.Bl -tag -width Er
+.It Bq Er EOVERFLOW
+Overflow occured when computing buffer size.
+.El
+.Pp
+The
+.Fn arena_alloc
+function and
+.Fn arena_new
+macro may fail and set the external variable
+.Va errno
+for any of the errors specified for the library function
+.Xr mmap 2 .
+.Sh SEE ALSO
+.Xr bufalloc 3
+.Sh AUTHORS
+.An Thomas Voss Aq Mt mail@thomasvoss.com
diff --git a/man/arena_free.3 b/man/arena_free.3
new file mode 100644
index 0000000..d6b1ee0
--- /dev/null
+++ b/man/arena_free.3
@@ -0,0 +1 @@
+.so arena_alloc.3
diff --git a/man/arena_new.3 b/man/arena_new.3
new file mode 100644
index 0000000..d6b1ee0
--- /dev/null
+++ b/man/arena_new.3
@@ -0,0 +1 @@
+.so arena_alloc.3
diff --git a/man/arena_zero.3 b/man/arena_zero.3
new file mode 100644
index 0000000..d6b1ee0
--- /dev/null
+++ b/man/arena_zero.3
@@ -0,0 +1 @@
+.so arena_alloc.3
diff --git a/man/mkarena.3 b/man/mkarena.3
new file mode 100644
index 0000000..d6b1ee0
--- /dev/null
+++ b/man/mkarena.3
@@ -0,0 +1 @@
+.so arena_alloc.3