Document MemoryHexDump() and DbExists()

This commit is contained in:
Jordan Bancino 2023-01-09 21:39:59 +00:00
parent b8ce4c9239
commit 599fa1a740
4 changed files with 59 additions and 17 deletions

View file

@ -22,12 +22,12 @@ Milestone: v0.2.0
[x] Password hashing
[~] User API
[x] Document MemoryHexDump()
[x] Document DbExists()
[ ] Document UserInteractiveAuth (move docs from Matrix)
[ ] Document User
[ ] Move docs from Matrix to User for UserValidate
[ ] Document MemoryHexDump()
[ ] Document Str and remove old functions from Util docs.
[ ] Document DbExists()
Milestone: v1.0.0
-----------------

View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: December 15 2022 $
.Dd $Mdocdate: January 9 2023 $
.Dt DB 3
.Os Telodendria Project
.Sh NAME
@ -18,6 +18,8 @@
.Fn DbLock "Db *" "size_t" "..."
.Ft int
.Fn DbUnlock "Db *" "DbRef *"
.Ft int
.Fn DbExists "Db *" "size_t" "..."
.Ft HashMap *
.Fn DbJson "DbRef *"
.Sh DESCRIPTION
@ -55,6 +57,17 @@ integrity.
unlocks an object and returns it back to the database, which syncs it to the
filesystem and caches it, if it isn't in the cache already.
.Pp
.Fn DbExists
checks the existence of the given database object in a more efficient
manner than attempting to lock it with
.Fn DbLock .
.Fn DbExists
does not lock the object, nor does it load it into memory if it exists. It
takes the same arguments as
.Fn DbLock
and
.Fn DbUnlock .
.Pp
.Fn DbJson
converts a database reference into JSON. At this time, the database actually
stores objects as JSON, so this just returns an internal pointer, but in the

View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: November 29 2022 $
.Dd $Mdocdate: January 9 2023 $
.Dt MEMORY 3
.Os Telodendria Project
.Sh NAME
@ -30,6 +30,8 @@
.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
@ -115,6 +117,14 @@ different. It also takes a memory action as the first argument. The
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

View file

@ -40,24 +40,43 @@ typedef enum MemoryAction
typedef struct MemoryInfo MemoryInfo;
extern void *MemoryAllocate(size_t, const char *, int);
extern void *MemoryReallocate(void *, size_t, const char *, int);
extern void MemoryFree(void *, const char *, int);
extern void *
MemoryAllocate(size_t, const char *, int);
extern size_t MemoryAllocated(void);
extern void MemoryFreeAll(void);
extern void *
MemoryReallocate(void *, size_t, const char *, int);
extern MemoryInfo *MemoryInfoGet(void *);
extern void
MemoryFree(void *, const char *, int);
extern size_t MemoryInfoGetSize(MemoryInfo *);
extern const char *MemoryInfoGetFile(MemoryInfo *);
extern int MemoryInfoGetLine(MemoryInfo *);
extern void *MemoryInfoGetPointer(MemoryInfo *);
extern size_t
MemoryAllocated(void);
extern void MemoryIterate(void (*) (MemoryInfo *, void *), void *);
extern void
MemoryFreeAll(void);
extern void MemoryHook(void (*) (MemoryAction, MemoryInfo *, void *), void *);
extern MemoryInfo *
MemoryInfoGet(void *);
extern void MemoryHexDump(MemoryInfo *, void (*) (size_t, char *, char *, void *), void *);
extern size_t
MemoryInfoGetSize(MemoryInfo *);
extern const char *
MemoryInfoGetFile(MemoryInfo *);
extern int
MemoryInfoGetLine(MemoryInfo *);
extern void *
MemoryInfoGetPointer(MemoryInfo *);
extern void
MemoryIterate(void (*) (MemoryInfo *, void *), void *);
extern void
MemoryHook(void (*) (MemoryAction, MemoryInfo *, void *), void *);
extern void
MemoryHexDump(MemoryInfo *, void (*) (size_t, char *, char *, void *), void *);
#endif