NAME
Db —
A minimal flat-file database with
object locking and an efficient cache.
SYNOPSIS
#include
<Db.h>
Db *
DbOpen(char
*, size_t);
void
DbClose(Db
*);
DbRef *
DbCreate(Db
*, size_t,
...);
int
DbDelete(Db
*, size_t,
...);
DbRef *
DbLock(Db
*, size_t,
...);
int
DbUnlock(Db
*, DbRef *);
int
DbExists(Db
*, size_t,
...);
Array *
DbList(Db
*, size_t,
...);
void
DbListFree(Array
*);
HashMap *
DbJson(DbRef
*);
DESCRIPTION
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.
DbOpen()
and
DbClose()
open and close a data directory. 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.
DbCreate()
and
DbLock()
load data objects from the database, with the notable difference being that
DbCreate() will fail if an object already exists,
and 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.
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.
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.
DbExists()
checks the existence of the given database object in a more efficient manner
than attempting to lock it with
DbLock().
DbExists() does not lock the object, nor does it
load it into memory if it exists. It takes the same arguments as
DbLock() and DbUnlock().
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.
DbDelete()
completely removes an object from the database. It purges it from both the
cache and the disk as soon as no more references to it are open.
DbList()
lists all of the objects at a given path. Unlike the other varargs
functions, it does not take a path to a specific object; it takes a
directory to be iterated. Note that the resulting list only contains the
objects in that directory, not subdirectories.
DbListFree()
frees the list returned by this function.
RETURN VALUES
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.
DbCreate() and
DbLock() return a database reference, or NULL if
there was an error obtaining a reference to the specified object.
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.
DbDelete() follows the same return value
conventions as DbUnlock(); it reports the status of
the deletion operation as a boolean value.
DbList() returns an array of strings, or
NULL if there was a memory or filesystem error.
DbJson() returns a JSON object. Consult
Json(3) for the API used to manipulate this object.