DB(3) Library Functions Manual DB(3)

DbA minimal flat-file database with object locking and an efficient cache.

#include <Db.h>

Db *
DbOpen(char *, size_t);

DbClose(Db *);

DbRef *
DbCreate(Db *, size_t, ...);

DbDelete(Db *, size_t, ...);

DbRef *
DbLock(Db *, size_t, ...);

DbUnlock(Db *, DbRef *);

DbExists(Db *, size_t, ...);

Array *
DbList(Db *, size_t, ...);

DbListFree(Array *);

HashMap *
DbJson(DbRef *);

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.

() and () 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.

() and () 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.

() 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.

() checks the existence of the given database object in a more efficient manner than attempting to lock it with (). 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().

() 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.

() 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.

() 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. () frees the list returned by this function.

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.

March 6, 2023 Telodendria Project