Document MemoryHexDump() and DbExists()

TODO.txt

@@ -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
 -----------------

man/man3/Db.3

@@ -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

man/man3/Memory.3

@@ -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 

src/include/Memory.h

@@ -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