libnmdb

NAME

libnmdb - Library for interacting with a nmdb server

SYNOPSYS

#include <nmdb.h>

nmdb_t *nmdb_init();
int nmdb_add_tipc_server(nmdb_t *db, int port);
int nmdb_add_tcp_server(nmdb_t *db, const char * addr, int port);
int nmdb_add_udp_server(nmdb_t *db, const char * addr, int port);
int nmdb_add_sctp_server(nmdb_t *db, const char * addr, int port);
int nmdb_free(nmdb_t *db);

int nmdb_set(nmdb_t *db,
             const unsigned char *key, size_t ksize,
             const unsigned char *val, size_t vsize);
int nmdb_set_sync(nmdb_t *db,
             const unsigned char *key, size_t ksize,
             const unsigned char *val, size_t vsize);
int nmdb_cache_set(nmdb_t *db,
             const unsigned char *key, size_t ksize,
             const unsigned char *val, size_t vsize);

ssize_t nmdb_get(nmdb_t *db,
             const unsigned char *key, size_t ksize,
             unsigned char *val, size_t vsize);
ssize_t nmdb_cache_get(nmdb_t *db,
             const unsigned char *key, size_t ksize,
             unsigned char *val, size_t vsize);

int nmdb_del(nmdb_t *db,
             const unsigned char *key, size_t ksize);
int nmdb_del_sync(nmdb_t *db,
             const unsigned char *key, size_t ksize);
int nmdb_cache_del(nmdb_t *db,
             const unsigned char *key, size_t ksize);

int nmdb_cas(nmdb_t *db,
             const unsigned char *key , size_t ksize,
             const unsigned char *oldval, size_t ovsize,
             const unsigned char *newval, size_t nvsize);
int nmdb_cache_cas(nmdb_t *db,
             const unsigned char *key , size_t ksize,
             const unsigned char *oldval, size_t ovsize,
             const unsigned char *newval, size_t nvsize);

int nmdb_incr(nmdb_t *db,
             const unsigned char *key , size_t ksize,
             int64_t increment, int64_t *newval);
int nmdb_cache_incr(nmdb_t *db,
             const unsigned char *key , size_t ksize,
             int64_t increment, int64_t *newval);

DESCRIPTION

libnmdb is a library for interacting with a nmdb(1) server. For more information about it, see nmdb(1) or http://blitiri.com.ar/p/nmdb.

The first step to access a server is to call nmdb_init() to initialize the data. It will return an opaque pointer of nmdb_t type, which well be used as the first argument for the rest of the functions and identifies a connection to the server.

Optionally, you can add more servers to the server pool, using nmdb_add_*_server(). You can add any number of servers, and each time a request is made, one will be selected. Be aware that you should add all the servers before start using the database. For nmdb_add_tipc_server(), nmdb_add_tcp_server(), nmdb_add_udp_server() and nmdb_add_sctp_server(), if you pass -1 as the port, it will select the default one. They return 1 on success or 0 on error (or if the specified protocol was not compiled in).

To dispose a connection, use nmdb_free().

The functions often take key and ksize arguments, as well as val and vsize. These represent a key and a value, respectively, along with their corresponding sizes, in bytes. The following restrictions regarding the size of the keys and values apply: keys can't exceed 64Kb, values can't exceed 64Kb, and the size of a key + the size of it's associated value can't exceed 64Kb.

There are five kinds of operations: set, which sets pairs; get, which gets pairs; del, which removes pairs; cas, which compares-and-sets values; and incr, which atomically increments a value. The normal set and del operations return as soon as they've been queued on the server for asynchronous completion. Note that in this case no message is sent to the client when the operation completes.

Each operation has variants, that make it behave in a different way. All three have "cache" variants, that only affect the cache and not the database; and set and del have "sync" variants that make the operation return only after it's been acknowledge complete by the database backend. All variants behave the same way as the original operation unless noted, so the following descriptions document them implicitly.

nmdb_set() is used to set the value associated with the given key. It returns 1 on success, or < 0 on failure.

nmdb_get() is used to retrieve the value for the given key, if there is any. The val parameter should be pointing to a buffer where the value will be placed, and vsize will be the size of that buffer. It's highly recommended that the buffer is greater than 64kb in size to make room for the largest possible value. It will return the size of the retrieved key (which will be put in the buffer pointed at by val), -1 if the requested key was not in the database (or cache, if the cache variant is used), or -2 on failure.

nmdb_del() is used to remove a given key (and it's associated value). The normal variant returns 1 if it was queued successfuly, or < 0 on failure. The cache and synchronous variant return 1 if the key was removed successfuly, 0 if the key was not in the database/cache, or < 0 on failure.

nmdb_cas() is used to compare-and-swap a key's value. It takes an old value to compare with the one in the database, and if they match, it sets the key to the given new value. Returns 2 if the swap was performed, 1 if the values didn't match, 0 if the key was not on in the database/cache, or < 0 on failure.

nmdb_incr() is used to atomically increment (or decrement) a key's value. It takes a 64 bit number to add to the value (it can be negative), and returns 2 if the increment was performed, 1 if the value was not in the appropriate format, 0 if the key was not in the database/cache, or < 0 on failure. The value MUST be a NULL-terminated string with only a number in base 10 in it (i.e. it must be parseable by strtoll(3)). If the number was incremented correctly and the newval parameter is not NULL, it will be set to the resulted value.

AUTHORS

Created by Alberto Bertogli (albertito@blitiri.com.ar).

CONTACT

If you want to report bugs, or have any questions or comments, just let me know at albertito@blitiri.com.ar.