diff --git a/TODO.txt b/TODO.txt index e87788e..2f893c0 100644 --- a/TODO.txt +++ b/TODO.txt @@ -41,9 +41,9 @@ Due: January 1, 2023 [x] Queue [ ] Routes [ ] TelodendriaConfig - [ ] Util + [x] Util [ ] Memory - [ ] Db + [x] Db Milestone: v1.0.0 ----------------- diff --git a/man/man3/Db.3 b/man/man3/Db.3 new file mode 100644 index 0000000..3a8859c --- /dev/null +++ b/man/man3/Db.3 @@ -0,0 +1,80 @@ +.Dd $Mdocdate: November 26 2022 $ +.Dt DB 3 +.Os Telodendria Project +.Sh NAME +.Nm Db +.Nd A minimal flat-file database with object locking and an efficient cache. +.Sh SYNOPSIS +.In Db.h +.Ft Db * +.Fn DbOpen "char *" "size_t" +.Ft void +.Fn DbClose "Db *" +.Ft DbRef * +.Fn DbCreate "Db *" "size_t" "..." +.Ft DbRef * +.Fn DbLock "Db *" "size_t" "..." +.Ft int +.Fn DbUnlock "Db *" "DbRef *" +.Ft HashMap * +.Fn DbJson "DbRef *" +.Sh DESCRIPTION +.Pp +Telodendria operates on a flat-file database instead of a traditional relational +database. This greatly simplifies the persistent storage code, and creates a +relatively basic API, described by this page. +.Pp +.Fn DbOpen +and +.Fn DbClose +open and close a data directory. +.Fn DbOpen +takes the path to open, and a cache size in bytes. This API relies heavily on +caching, so the cache must be greater than the DB_MIN_CACHE preprocessor +constant. +.Pp +.Fn DbCreate +and +.Fn DbLock +load data objects from the database, with the notable difference being that +.Fn DbCreate +will fail if an object already exists, and +.Fn DbLock +will fail if an object does not exist. These are both variadic functions that +take a variable number of C strings, with the exact number being specified by +the second paramter. These C strings are used to generate a filesystem path from +which an object is loaded, unless it is already in the cache. +.Pp +Objects, when loaded, are locked both in memory and on disk, so that other threads +or processes cannot access them while they are locked. This is to ensure data +integrity. +.Pp +.Fn DbUnlock +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 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 +future it may have to be generated by decompressing a binary blob, or something +of that nature. +.Sh RETURN VALUES +.Pp +.Fn DbOpen +returns a reference to a database pointer, or NULL if there was an error +allocating memory, or opening the given directory with the given cache size. +.Pp +.Fn DbCreate +and +.Fn DbLock +return a database reference, or NULL if there was an error obtaining a reference +to the specified object. +.Pp +.Fn DbUnlock +returns a boolean value indicating whether or not the reference was successfully +unlocked. If the unlock is successful, then a non-zero value is returned. If it +isn't, 0 is returned, and it is up to the caller to decide how to proceed. +.Fn DbJson +returns a JSON object. Consult +.Xr Json 3 +for the API used to manipulate this object. diff --git a/site/index.html b/site/index.html index b76f236..c40ca4c 100644 --- a/site/index.html +++ b/site/index.html @@ -210,6 +210,13 @@ Logging framework used to log messages in Telodendria. Misc utility functions that don't need their own header. + +Db(3) + +A minimal flat-file database with object locking and an efficient +cache. + +

Resources