Add Db(3)

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

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.

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.
 </td>
 </tr>
+<tr>
+<td><a href="man/man3/Db.3.html">Db(3)</a></td>
+<td>
+A minimal flat-file database with object locking and an efficient
+cache.
+</td>
+</tr>
 </table>
 <h2 id="resources">Resources</h2>
 <ul>