Import new Cytoplasm library based off of code from Telodendria.

Telodendria doesn't use this library yet, but it will soon.

src/include/Memory.h

@@ -0,0 +1,225 @@
+/*
+ * Copyright (C) 2022-2023 Jordan Bancino <@jordan:bancino.net>
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation files
+ * (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+#ifndef CYTOPLASM_MEMORY_H
+#define CYTOPLASM_MEMORY_H
+
+/***
+ * @Nm Memory
+ * @Nd Smart memory management.
+ * @Dd January 9 2023
+ *
+ * .Nm
+ * is an API that allows for smart memory management and profiling. It
+ * wraps the standard library functions
+ * .Xr malloc 3 ,
+ * .Xr realloc 3 ,
+ * and
+ * .Xr free 3 ,
+ * and offers identical semantics, while providing functionality that
+ * the standard library doesn't have, such as getting statistics on the
+ * total memory allocated on the heap, and getting the size of a block
+ * given a pointer. Additionally, thanks to preprocessor macros, the
+ * exact file and line number at which an allocation, re-allocation, or
+ * free occured can be obtained given a pointer. Finally, all the
+ * blocks allocated on the heap can be iterated and evaluated, and a
+ * callback function can be executed every time a memory operation
+ * occurs.
+ * .Pp
+ * In the future, this API could include a garbage collector that
+ * automatically frees memory it detects as being no longer in use.
+ * However, this feature does not yet exist.
+ * .Pp
+ * A number of macros are available, which make the
+ * .Nm
+ * API much easier to use. They are as follows:
+ * .Bl -bullet -offset indent
+ * .It
+ * .Fn Malloc "x"
+ * .It
+ * .Fn Realloc "x" "y"
+ * .It
+ * .Fn Free "x"
+ * .El
+ * .Pp
+ * These macros expand to
+ * .Fn MemoryAllocate ,
+ * .Fn MemoryReallocate ,
+ * and
+ * .Fn MemoryFree
+ * with the second and third parameters set to __FILE__ and __LINE__.
+ * This allows
+ * .Nm
+ * to be used exactly how the standard library functions would be
+ * used. In fact, the functions to which these macros expand are not
+ * intended to be used directly; for the best results, use these
+ * macros.
+ */
+#include <stddef.h>
+
+/**
+ * These values are passed into the memory hook function to indicate
+ * the action that just happened.
+ */
+typedef enum MemoryAction
+{
+    MEMORY_ALLOCATE,
+    MEMORY_REALLOCATE,
+    MEMORY_FREE,
+    MEMORY_BAD_POINTER
+} MemoryAction;
+
+#define Malloc(x) MemoryAllocate(x, __FILE__, __LINE__)
+#define Realloc(x, s) MemoryReallocate(x, s, __FILE__, __LINE__)
+#define Free(x) MemoryFree(x, __FILE__, __LINE__)
+
+/**
+ * The memory information is opaque, but can be accessed using the
+ * functions defined by this API.
+ */
+typedef struct MemoryInfo MemoryInfo;
+
+/**
+ * Allocate the specified number of bytes on the heap. This function
+ * has the same semantics as
+ * .Xr malloc 3 ,
+ * except that it takes the file name and line number at which the
+ * allocation occurred.
+ */
+extern void * MemoryAllocate(size_t, const char *, int);
+
+/**
+ * Change the size of the object pointed to by the given pointer
+ * to the given number of bytes. This function has the same semantics
+ * as
+ * .Xr realloc 3 ,
+ * except that it takes the file name and line number at which the
+ * reallocation occurred.
+ */
+extern void * MemoryReallocate(void *, size_t, const char *, int);
+
+/**
+ * Free the memory at the given pointer. This function has the same
+ * semantics as
+ * .Xr free 3 ,
+ * except that it takes the file name and line number at which the
+ * free occurred.
+ */
+extern void MemoryFree(void *, const char *, int);
+
+/**
+ * Get the total number of bytes that the program has allocated on the
+ * heap. This operation iterates over all heap allocations made with
+ * .Fn MemoryAllocate
+ * and then returns a total count, in bytes.
+ */
+extern size_t MemoryAllocated(void);
+
+/**
+ * Iterate over all heap allocations made with
+ * .Fn MemoryAllocate
+ * and call
+ * .Fn MemoryFree
+ * on them. This function immediately invalidates all pointers to
+ * blocks on the heap, and any subsequent attempt to read or write to
+ * data on the heap will result in undefined behavior. This is
+ * typically called at the end of the program, just before exit.
+ */
+extern void MemoryFreeAll(void);
+
+/**
+ * Fetch information about an allocation. This function takes a raw
+ * pointer, and if
+ * . Nm
+ * knows about the pointer, it returns a structure that can be used
+ * to obtain information about the block of memory that the pointer
+ * points to.
+ */
+extern MemoryInfo * MemoryInfoGet(void *);
+
+/**
+ * Get the size in bytes of the block of memory represented by the
+ * specified memory info structure.
+ */
+extern size_t MemoryInfoGetSize(MemoryInfo *);
+
+/**
+ * Get the file name in which the block of memory represented by the
+ * specified memory info structure was allocated.
+ */
+extern const char * MemoryInfoGetFile(MemoryInfo *);
+
+/**
+ * Get the line number on which the block of memory represented by the
+ * specified memory info structure was allocated.
+ */
+extern int MemoryInfoGetLine(MemoryInfo *);
+
+/**
+ * Get a pointer to the block of memory represented by the specified
+ * memory info structure.
+ */
+extern void * MemoryInfoGetPointer(MemoryInfo *);
+
+/**
+ * This function takes a pointer to a function that takes the memory
+ * info structure, as well as a void pointer for caller-provided
+ * arguments. It iterates over all the heap memory currently allocated
+ * at the time of calling, executing the function on each allocation.
+ */
+extern void MemoryIterate(void (*) (MemoryInfo *, void *), void *);
+
+/**
+ * Specify a function to be executed whenever a memory operation
+ * occurs. The MemoryAction argument specifies the operation that
+ * occurred on the block of memory represented by the memory info
+ * structure. The function also takes a void pointer to caller-provided
+ * arguments.
+ */
+extern void MemoryHook(void (*) (MemoryAction, MemoryInfo *, void *), void *);
+
+/**
+ * Read over the block of memory represented by the given memory info
+ * structure and generate a hexadecimal and ASCII string for each
+ * chunk of the block. This function takes a callback function that
+ * takes the following parameters in order:
+ * .Bl -bullet -offset indent
+ * .It
+ * The current offset from the beginning of the block of memory in
+ * bytes.
+ * .It
+ * A null-terminated string containing the next 16 bytes of the block
+ * encoded as space-separated hex values.
+ * .It
+ * A null-terminated string containing the ASCII representation of the
+ * same 16 bytes of memory. This ASCII representation is safe to print
+ * to a terminal or other text device, because non-printable characters
+ * are encoded as a . (period).
+ * .It
+ * Caller-passed pointer.
+ * .El
+ */
+extern void
+MemoryHexDump(MemoryInfo *, void (*) (size_t, char *, char *, void *), void *);
+
+#endif