forked from lda/telodendria
Document Memory API
This commit is contained in:
parent
643bdb2ec7
commit
27da9ed88f
3 changed files with 142 additions and 1 deletions
2
TODO.txt
2
TODO.txt
|
|
@ -42,7 +42,7 @@ Due: January 1, 2023
|
|||
[ ] Routes
|
||||
[ ] TelodendriaConfig
|
||||
[x] Util
|
||||
[ ] Memory
|
||||
[x] Memory
|
||||
[x] Db
|
||||
|
||||
Milestone: v1.0.0
|
||||
|
|
|
|||
135
man/man3/Memory.3
Normal file
135
man/man3/Memory.3
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
.Dd $Mdocdate: November 29 2022 $
|
||||
.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 *"
|
||||
.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.
|
||||
.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.
|
||||
|
||||
|
|
@ -223,6 +223,12 @@ A minimal flat-file database with object locking and an efficient
|
|||
cache.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="man/man3/Memory.3.html">Memory(3)</a></td>
|
||||
<td>
|
||||
Smart memory management API.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<h2 id="resources">Resources</h2>
|
||||
<ul>
|
||||
|
|
|
|||
Loading…
Reference in a new issue