Add Db(3)

This commit is contained in:
Jordan Bancino 2022-11-26 20:39:47 +00:00
parent e066e90d1d
commit 889a16856d
3 changed files with 89 additions and 2 deletions

View file

@ -41,9 +41,9 @@ Due: January 1, 2023
[x] Queue
[ ] Routes
[ ] TelodendriaConfig
[ ] Util
[x] Util
[ ] Memory
[ ] Db
[x] Db
Milestone: v1.0.0
-----------------

80
man/man3/Db.3 Normal file
View file

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

View file

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