telodendria/include/Cytoplasm/Memory.h
Jordan Bancino 461357b526 Move headers from src/include to include/Cytoplasm.
This makes it easier to build Cytoplasm as a component of another
program (for example, Telodendria), or as a standalone system library.
2024-01-13 18:40:31 -05:00

236 lines
7.8 KiB
C

/*
* Copyright (C) 2022-2024 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>
#include <stdint.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,
MEMORY_CORRUPTED
} 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 *);
/**
* The default memory hook, which has sane behavior and is installed
* at runtime. This function does not use any memory on the heap,
* except for the MemoryInfo passed to it, which it assumes to be
* valid. Everything else happens on the stack only, to ensure that
* the hook doesn't make any memory problems worse.
*/
extern void MemoryDefaultHook(MemoryAction, MemoryInfo *, 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