forked from Telodendria/Telodendria
80 lines
2.6 KiB
Groff
80 lines
2.6 KiB
Groff
.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.
|