forked from Telodendria/Telodendria
Add Db(3)
This commit is contained in:
parent
e066e90d1d
commit
889a16856d
3 changed files with 89 additions and 2 deletions
4
TODO.txt
4
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
|
||||
-----------------
|
||||
|
|
80
man/man3/Db.3
Normal file
80
man/man3/Db.3
Normal 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.
|
|
@ -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>
|
||||
|
|
Loading…
Reference in a new issue