README.md

kvsm

Key-value storage machine

Installing

This library makes use of dep to manage it's dependencies and exports.

dep add finwo/kvsm@main

About

Why

Well, I wanted something simple that I can embed into other applications. This library is designed to be simple, not to break any records.

How

This library makes use of palloc to handle blob allocations on a file or block device. Each blob represents a transaction.

From there, a transaction contains one or more parent references, an increment number and a list of key-value pairs.

This in turn allows for out-of-order insertion of transactions, compaction of older transactions, and even having multiple nodes sync up their transactions in a deterministic manner

API

Definitions

KVSM_RESPONSE

A type declaring state-based responses

#define KVSM_RESPONSE int

KVSM_OK

A response declaring the method executed succesfully

#define KVSM_OK 0

KVSM_ERRROR

A response declaring the method executed with a failure

#define KVSM_ERROR 1

Structures

struct kvsm

Represents a state descriptor for kvsm, holds internal state

struct kvsm {
 PALLOC_FD      fd;
 PALLOC_OFFSET *head;
 int            head_count;
};

struct kvsm_transaction

TBD

struct kvsm_transaction {
 const struct kvsm *ctx;
 const struct buf  *id;
 PALLOC_OFFSET     *parent;
 int                parent_count;
};

Methods

kvsm_open(filename, isBlockDev)

Initializes a new struct kvsm, handling creating the file if needed. Returns a new descriptor or NULL on failure.

struct kvsm * kvsm_open(const char *filename, const int isBlockDev);

kvsm_close(ctx)

Closes the given kvsm descriptor and frees it.

KVSM_RESPONSE kvsm_close(struct kvsm *ctx);

kvsm_compact(ctx)

Reduces used storage by removing all transactions only containing non-current versions.

KVSM_RESPONSE kvsm_compact(const struct kvsm *ctx);

kvsm_get(ctx, key)

Searches the kvsm medium, returning a buffer with the value or NULL if not found

struct buf * kvsm_get(const struct kvsm *ctx, const struct buf *key);

kvsm_set(ctx, key, value)

Writes a value to the kvsm medium on the given key

KVSM_RESPONSE kvsm_set(struct kvsm *ctx, const struct buf *key, const struct buf *value);

kvsm_del(ctx, key)

Writes a tombstone to the kvsm medium on the given key

#define kvsm_del(ctx,key) (kvsm_set(ctx,key,&((struct buf){ .len = 0, .cap = 0 })))

Example

This library includes kvsmctl as an example program making use of this library.

Many bugs were caught implementing and playing with it, but feel free to open an issue when you encounter something unexpected.