diff --git a/TODO.txt b/TODO.txt index a2ed5b3..ab5c04d 100644 --- a/TODO.txt +++ b/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 ----------------- diff --git a/man/man3/Db.3 b/man/man3/Db.3 index 06daca1..b2233cf 100644 --- a/man/man3/Db.3 +++ b/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 diff --git a/man/man3/Memory.3 b/man/man3/Memory.3 index a01ed32..3033aae 100644 --- a/man/man3/Memory.3 +++ b/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 diff --git a/src/include/Memory.h b/src/include/Memory.h index 5503546..7146f77 100644 --- a/src/include/Memory.h +++ b/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