File mod/kdb/kdb.md artifact 1c2867c8a9 part of check-in 81758652b5
kdb
kdb is a module for storing and loading data from files.
model
the first argument to all kdb functions is of type struct kdb
, which describes the database to be accessed. the first field of that struct is a pointer to a struct of type struct kdb_fmt
which describes the format of the database.
kdb encodes records as a tuple of three fields: (kind, key, value). kind
is a 16-bit integer, key
is an integer of platform width, and value
is a blob decoded according to the type of the record, which is not saved in the database itself. records are indexed by the tuple (kind, key); key
may be null. kind
denotes the structure of the record, and is user-defined.
to use strings as the keys for database entries, either atoms should be stored in the database or a hash function may be used. kdb contains procedures to automate the use of atoms as keys.
types
struct kdb
struct kdb_fmt* fmt
enum kdb_conn conn
union { kfile* file; const kdb_store* mem; kmptr ptr; } store;
struct kdb_rec
u16 kind
word key
ksraw value
enum kdb_conn
kdb_conn_none
: no database is connected; calls will failkdb_conn_file
: the database is stored in a file; calls to modify it will modify the file on-diskkdb_conn_file_static
: the database is stored in a file; calls to modify it will fail. if the file is writable to the process, can be seamlessly changed tokdb_conn_file
and vice-versakdb_conn_mem
: the database is stored in-memory, allocated by kmem and referenced byptr
. calls to modify it will re-allocate memory via the appropriate interfaces.kdb_conn_mem_static
: the database is stored in-memory, referenced bymem
; calls to modify it will fail