forked from Telodendria/Telodendria
145 lines
4.7 KiB
Groff
145 lines
4.7 KiB
Groff
.Dd $Mdocdate: January 9 2023 $
|
|
.Dt MEMORY 3
|
|
.Os Telodendria Project
|
|
.Sh NAME
|
|
.Nm Memory
|
|
.Nd Smart memory management.
|
|
.Sh SYNOPSIS
|
|
.In Memory.h
|
|
.Ft void *
|
|
.Fn MemoryAllocate "size_t" "const char *" "int"
|
|
.Ft void *
|
|
.Fn MemoryReallocate "void *" "size_t" "const char *" "int"
|
|
.Ft void
|
|
.Fn MemoryFree "void *" "const char *" "int"
|
|
.Ft size_t
|
|
.Fn MemoryAllocated "void"
|
|
.Ft void
|
|
.Fn MemoryFreeAll "void"
|
|
.Ft MemoryInfo *
|
|
.Fn MemoryInfoGet "void *"
|
|
.Ft size_t
|
|
.Fn MemoryInfoGetSize "MemoryInfo *"
|
|
.Ft const char *
|
|
.Fn MemoryInfoGetFile "MemoryInfo *"
|
|
.Ft int
|
|
.Fn MemoryInfoGetLine "MemoryInfo *"
|
|
.Ft void *
|
|
.Fn MemoryInfoGetPointer "MemoryInfo *"
|
|
.Ft void
|
|
.Fn MemoryIterate "void (*) (MemoryInfo *, void *)" "void *"
|
|
.Ft void
|
|
.Fn MemoryHook "void (*) (MemoryAction, MemoryInfo *, void *" "void *"
|
|
.Ft void
|
|
.Fn MemoryHexDump "MemoryInfo *" "void (*) (size_t, char *, char *, void *)" "void *"
|
|
.Sh DESCRIPTION
|
|
.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 of memory
|
|
given a pointer. Additionally, thanks to preprocessor macros, the exact
|
|
file and line number at which an allocation, reallocation, 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
|
|
A number of macros are available, which make using the
|
|
.Nm
|
|
API much more useful.
|
|
.Fn Malloc
|
|
expands to
|
|
.Fn MemoryAllocate
|
|
with the __FILE__ and __LINE__ constants for the second and third
|
|
arguments respectively. Likewise,
|
|
.Fn Realloc
|
|
and
|
|
.Fn Free
|
|
expand to
|
|
.Fn MemoryReallocate
|
|
and
|
|
.Fn MemoryFree
|
|
with __FILE__ and __LINE__ as the second and third parameters.
|
|
This allows the API to be used exactly how the standard library
|
|
would be used. In fact, the functions which these macros expand to
|
|
are not intended to be called directly; only use the macros for the
|
|
best results.
|
|
.Pp
|
|
If all memory used in the program is managed by this API, there are some
|
|
helpful functions that allow the program to probe the state of the heap.
|
|
These functions are described here.
|
|
.Pp
|
|
.Fn MemoryAllocated
|
|
gets the total memory that the program has on the heap. This operation
|
|
iterates over all the heap allocations made with
|
|
.Fn MemoryAllocate
|
|
and then returns a total count, in bytes.
|
|
.Pp
|
|
.Fn MemoryFreeAll
|
|
iterates over all the heap allocations made with
|
|
.Fn MemoryAllocate
|
|
and calls
|
|
.Fn MemoryFree
|
|
on them. It immediately invalidates all pointers, and any subsequent
|
|
reads or writes to heap memory result in undefined behavior. This
|
|
is typically used at the end of the program.
|
|
.Pp
|
|
.Fn MemoryInfoGet
|
|
takes a pointer and fetches information about it, storing it in a
|
|
structure that can then be queried.
|
|
.Pp
|
|
.Fn MemoryInfoGetSize ,
|
|
.Fn MemoryInfoGetFile ,
|
|
.Fn MemoryInfoGetLine ,
|
|
and
|
|
.Fn MemoryInfoGetPointer
|
|
all take in the structure returned by
|
|
.Fn MemoryInfoGet ,
|
|
and return the respective property about the given property. These are
|
|
especially useful for logging and debugging with
|
|
.Fn MemoryIterate
|
|
and
|
|
.Fn MemoryHook .
|
|
.Pp
|
|
.Fn MemoryIterate
|
|
takes a pointer to a function that takes the memory information 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.
|
|
.Fn MemoryHook
|
|
has a similar prototype, although the function pointer it takes is slightly
|
|
different. It also takes a memory action as the first argument. The
|
|
.Nm
|
|
API stores the pointer to this function, and executes it every time memory
|
|
is allocated, reallocated, or freed. This allows a program to execute code
|
|
whenever memory is allocated.
|
|
.Pp
|
|
.Fn MemoryHexDump
|
|
can be useful for debugging memory errors. It reads over a block of memory
|
|
and generates a hexadecimal and an ASCII string for each chunk of the block.
|
|
It takes a memory infomation structure and a callback function that processes
|
|
the offset, hexadecimal string, and ASCII string. This callback function
|
|
typically prints the strings out to a console, file, or other output
|
|
device.
|
|
.Sh RETURN VALUES
|
|
.Pp
|
|
.Fn MemoryAllocate
|
|
and
|
|
.Fn MemoryReallocate
|
|
return the same as their standard library counterparts. That is, a pointer
|
|
to memory on the heap, or NULL if there was an error allocating it.
|
|
.Pp
|
|
.Fn MemoryInfoGet
|
|
returns a pointer to information about a block on the heap, or NULL if the
|
|
passed pointer was not allocated by the
|
|
.Nm
|
|
API, or is no longer allocated.
|
|
.Pp
|
|
.Fn MemoryAllocated
|
|
returns an unsigned integer that indicates the number of bytes currently
|
|
allocated on the heap.
|
|
|