libnmdb/nmdb.h

   1
   2 /* Header for the libnmdb library. */
   3
   4 #ifndef _NMDB_H
   5 #define _NMDB_H
   6
   7 #include <stdlib.h>     /* size_t, ssize_t */
   8
   9 /** Opaque type representing a connection with one or more servers. */
  10 typedef struct nmdb_conn nmdb_t;
  11
  12
  13 /**
  14  * @addtogroup connection Connection API
  15  * Functions used to connect to the servers.
  16  */
  17
  18 /** Create a new nmdb_t pointer, used to talk with the server.
  19  *
  20  * @returns a new connection instance.
  21  * @ingroup connection
  22  */
  23 nmdb_t *nmdb_init();
  24
  25 /** Add a TIPC server.
  26  *
  27  * @param db connection instance.
  28  * @param port TIPC port to connect to (-1 means use the default).
  29  * @returns 1 on success, 0 on failure.
  30  * @ingroup connection
  31  */
  32 int nmdb_add_tipc_server(nmdb_t *db, int port);
  33
  34 /** Add a TCP server.
  35  *
  36  * @param db connection instance.
  37  * @param addr host to connect to.
  38  * @param port port to connect to (-1 means use the default).
  39  * @returns 1 on success, 0 on failure.
  40  * @ingroup connection
  41  */
  42 int nmdb_add_tcp_server(nmdb_t *db, const char *addr, int port);
  43
  44 /** Add an UDP server.
  45  *
  46  * @param db connection instance.
  47  * @param addr host to connect to.
  48  * @param port port to connect to (-1 means use the default).
  49  * @returns 1 on success, 0 on failure.
  50  * @ingroup connection
  51  */
  52 int nmdb_add_udp_server(nmdb_t *db, const char *addr, int port);
  53
  54 /** Add a SCTP server.
  55  *
  56  * @param db connection instance.
  57  * @param addr host to connect to.
  58  * @param port port to connect to (-1 means use the default).
  59  * @returns 1 on success, 0 on failure.
  60  * @ingroup connection
  61  */
  62 int nmdb_add_sctp_server(nmdb_t *db, const char *addr, int port);
  63
  64 /** Free a nmdb_t structure created by nmdb_init().
  65  * It also closes all the connections opened to the servers.
  66  *
  67  * @param db connection instance.
  68  * @returns 1 on success, 0 on failure.
  69  * @ingroup connection
  70  */
  71 int nmdb_free(nmdb_t *db);
  72
  73
  74 /**
  75  * @addtogroup database Database API
  76  * Functions that affect the database and the cache.
  77  *
  78  * @addtogroup cache Cache API
  79  * Functions that affect only the cache.
  80  */
  81
  82 /** Get the value associated with a key.
  83  *
  84  * @param db connection instance.
  85  * @param key the key.
  86  * @param ksize the key size.
  87  * @param[out] val buffer where the value will be stored.
  88  * @param vsize size of the value buffer.
  89  * @returns the size of the value written to the given buffer, -1 if the key
  90  *      is not in the database, or -2 if there was an error.
  91  * @ingroup database
  92  */
  93 ssize_t nmdb_get(nmdb_t *db, const unsigned char *key, size_t ksize,
  94                 unsigned char *val, size_t vsize);
  95
  96 /** Get the value associated with a key from cache.
  97  * This is just like nmdb_get(), except it only queries the caches, and never
  98  * the database.
  99  *
 100  * @param db connection instance.
 101  * @param key the key.
 102  * @param ksize the key size.
 103  * @param[out] val buffer where the value will be stored.
 104  * @param vsize size of the value buffer.
 105  * @returns the size of the value written to the given buffer, -1 if the key
 106  *      is not in the cache, or -2 if there was an error.
 107  * @ingroup cache
 108  */
 109 ssize_t nmdb_cache_get(nmdb_t *db, const unsigned char *key, size_t ksize,
 110                 unsigned char *val, size_t vsize);
 111
 112 /** Set the value associated with a key.
 113  * It returns after the command has been acknowledged by the server, but does
 114  * not wait for the database to confirm it. In any case, further GET requests
 115  * will return this value, even if this set has not reached the backend yet.
 116  *
 117  * @param db connection instance.
 118  * @param key the key.
 119  * @param ksize the key size.
 120  * @param val the value
 121  * @param vsize size of the value.
 122  * @returns 1 on success, < 0 on error.
 123  * @ingroup database
 124  */
 125 int nmdb_set(nmdb_t *db, const unsigned char *key, size_t ksize,
 126                 const unsigned char *val, size_t vsize);
 127
 128 /** Set the value associated with a key, synchronously.
 129  * It works just like nmdb_set(), except it returns only after the database
 130  * confirms it has stored the value.
 131  *
 132  * @param db connection instance.
 133  * @param key the key.
 134  * @param ksize the key size.
 135  * @param val the value
 136  * @param vsize size of the value.
 137  * @returns 1 on success, < 0 on error.
 138  * @ingroup database
 139  */
 140 int nmdb_set_sync(nmdb_t *db, const unsigned char *key, size_t ksize,
 141                 const unsigned char *val, size_t vsize);
 142
 143 /** Set the value associated with a key, but only in the cache.
 144  * This command sets the key's value in the cache, but does NOT affect the
 145  * backend database. Combining it with nmdb_set() and/or nmdb_set_sync() is
 146  * not recommended, because consistency issues may arise.
 147  *
 148  * @param db connection instance.
 149  * @param key the key.
 150  * @param ksize the key size.
 151  * @param val the value
 152  * @param vsize size of the value.
 153  * @returns 1 on success, < 0 on error.
 154  * @ingroup cache
 155  */
 156 int nmdb_cache_set(nmdb_t *db, const unsigned char *key, size_t ksize,
 157                 const unsigned char *val, size_t vsize);
 158
 159 /** Delete a key.
 160  * It returns after the command has been acknowledged by the server, but does
 161  * not wait for the database to confirm it. In any case, further GET requests
 162  * will return the key is missing, even if this delete has not reached the
 163  * backend yet.
 164  *
 165  * @param db connection instance.
 166  * @param key the key.
 167  * @param ksize the key size.
 168  * @returns 1 on success, < 0 on error.
 169  * @ingroup database
 170  */
 171 int nmdb_del(nmdb_t *db, const unsigned char *key, size_t ksize);
 172
 173 /** Delete a key synchronously.
 174  * It works just like nmdb_del(), except it returns only after the database
 175  * confirms it has deleted the key.
 176  *
 177  * @param db connection instance.
 178  * @param key the key.
 179  * @param ksize the key size.
 180  * @returns 1 on success, < 0 on error.
 181  * @ingroup database
 182  */
 183 int nmdb_del_sync(nmdb_t *db, const unsigned char *key, size_t ksize);
 184
 185 /** Delete a key, but only from the cache.
 186  * This command deletes a key from the cache, but does NOT affect the backend
 187  * database. Combining it with nmdb_del() and/or nmdb_del_sync() is not
 188  * recommended, because consistency issues may arise.
 189  *
 190  * @param db connection instance.
 191  * @param key the key.
 192  * @param ksize the key size.
 193  * @returns 1 on success, < 0 on error.
 194  * @ingroup cache
 195  */
 196 int nmdb_cache_del(nmdb_t *db, const unsigned char *key, size_t ksize);
 197
 198 /** Perform an atomic compare-and-swap.
 199  * This command will set the value associated to a key to newval, provided it
 200  * currently is oldval, in an atomic way.
 201  * Equivalent to atomically doing:
 202  *
 203  *      if get(key) == oldval, then set(key, newval)
 204  *
 205  * @param db connection instance.
 206  * @param key the key.
 207  * @param ksize the key size.
 208  * @param oldval the old, expected value.
 209  * @param ovsize size of the expected value.
 210  * @param newval the new value to set.
 211  * @param nvsize size of the new value.
 212  * @returns 2 on success, 1 if the current value does not match oldval, 0 if
 213  *      the key is not in the database, or < 0 on error.
 214  * @ingroup database
 215  */
 216 int nmdb_cas(nmdb_t *db, const unsigned char *key, size_t ksize,
 217                 const unsigned char *oldval, size_t ovsize,
 218                 const unsigned char *newval, size_t nvsize);
 219
 220 /** Perform an atomic compare-and-swap only on the cache.
 221  * This command works just like nmdb_cas(), except it affects only the cache,
 222  * and not the backend database.
 223  * Equivalent to atomically doing:
 224  *
 225  *      if get_cache(key) == oldval, then set_cache(key, newval)
 226  *
 227  * @param db connection instance.
 228  * @param key the key.
 229  * @param ksize the key size.
 230  * @param oldval the old, expected value.
 231  * @param ovsize size of the expected value.
 232  * @param newval the new value to set.
 233  * @param nvsize size of the new value.
 234  * @returns 2 on success, 1 if the current value does not match oldval, 0 if
 235  *      the key is not in the database, or < 0 on error.
 236  * @ingroup cache
 237  */
 238 int nmdb_cache_cas(nmdb_t *db, const unsigned char *key, size_t ksize,
 239                 const unsigned char *oldval, size_t ovsize,
 240                 const unsigned char *newval, size_t nvsize);
 241
 242 /** Atomically increment the value associated with a key.
 243  * This command atomically increments the value associated with a key in the
 244  * given increment. However, there are requirements on the current value: it
 245  * must be a NULL-terminated string with only a number in base 10 in it (i.e.
 246  * it must be parseable by strtoll(3)).
 247  *
 248  * @param db connection instance.
 249  * @param key the key.
 250  * @param ksize the key size.
 251  * @param increment the value to add to the current one (can be negative).
 252  * @param[out] newval pointer to an integer that will be set to the new
 253  *      value.
 254  * @returns 2 if the increment was successful, 1 if the current value was not
 255  *      in an appropriate format, 0 if the key is not in the database, or < 0
 256  *      on error.
 257  * @ingroup database
 258  */
 259 int nmdb_incr(nmdb_t *db, const unsigned char *key, size_t ksize,
 260                 int64_t increment, int64_t *newval);
 261
 262 /** Atomically increment the value associated with a key only in the cache.
 263  * This command works just like nmdb_incr(), except it affects only the cache,
 264  * and not the backend database.
 265  *
 266  * @param db connection instance.
 267  * @param key the key.
 268  * @param ksize the key size.
 269  * @param increment the value to add to the current one (can be negative).
 270  * @param[out] newval pointer to an integer that will be set to the new
 271  *      value.
 272  * @returns 2 if the increment was successful, 1 if the current value was not
 273  *      in an appropriate format, 0 if the key is not in the database, or < 0
 274  *      on error.
 275  * @ingroup cache
 276  */
 277 int nmdb_cache_incr(nmdb_t *db, const unsigned char *key, size_t ksize,
 278                 int64_t increment, int64_t *newval);
 279
 280
 281 /**
 282  * @addtogroup utility Functions used in nmdb utilities
 283  * These functions are used almost exclusively by nmdb utilities, although
 284  * they may be used by external applications. They often require some
 285  * knowledge about nmdb's inner workings so they should be used with care.
 286  */
 287
 288 /** Get the first key.
 289  * Returns the first key in the database, which can then be used to get the
 290  * following one with nmdb_nextkey(). Together, they can be used to iterate
 291  * over all the keys of a *single server*.  It has some caveats:
 292  *
 293  *  - It will fail if db has more than one server.
 294  *  - If the database is being modified during iteration, the walk can result
 295  *    in skipping nodes or walking the same one twice.
 296  *  - There is absolutely no guarantee about the order of the keys.
 297  *  - The order is not stable and must not be relied upon.
 298  *
 299  * This is almost exclusively used for replication utilities.
 300  *
 301  * @param db connection instance.
 302  * @param[out] key the first key.
 303  * @param ksize the key size.
 304  * @returns -2 on error, -1 if the database is empty, or the key size on
 305  *      success.
 306  * @ingroup utility
 307  */
 308 ssize_t nmdb_firstkey(nmdb_t *db, unsigned char *key, size_t ksize);
 309
 310 /** Get the key that follows the one given.
 311  * Together with nmdb_firstkey(), they can be used to iterate This function,
 312  * along with nmdb_firstkey(), are used to iterate over all the keys of a
 313  * *single server*. It has some caveats:
 314  *
 315  *  - It will fail if db has more than one server.
 316  *  - If the database is being modified during iteration, the walk can result
 317  *    in skipping nodes or walking the same one twice.
 318  *  - There is absolutely no guarantee about the order of the keys.
 319  *  - The order is not stable and must not be relied upon.
 320  *
 321  * This is almost exclusively used for replication utilities.
 322  *
 323  * @param db connection instance.
 324  * @param key the current key.
 325  * @param ksize the current key size.
 326  * @param[out] newkey the key that follows the current one.
 327  * @param nksize the newkey size.
 328  * @returns -2 on error, -1 if the database is empty, or the new key size on
 329  *      success.
 330  * @ingroup utility
 331  */
 332 ssize_t nmdb_nextkey(nmdb_t *db, const unsigned char *key, size_t ksize,
 333                 unsigned char *newkey, size_t nksize);
 334
 335
 336 /** Request servers' statistics.
 337  * This API is used by nmdb-stats, and likely to change in the future. Do not
 338  * rely on it.
 339  *
 340  * @param db connection instance.
 341  * @param[out] buf buffer used to store the results.
 342  * @param bsize size of the buffer.
 343  * @param[out] nservers number of servers queried.
 344  * @param [out] nstats number of stats per server.
 345  * @returns 1 if success, -1 if there was an error in the server, -2 if there
 346  *      was a network error, -3 if the buffer was too small, -4 if the server
 347  *      replies were of different size (indicates different server versions,
 348  *      not supported at the time)
 349  * @ingroup utility
 350  */
 351 int nmdb_stats(nmdb_t *db, unsigned char *buf, size_t bsize,
 352                 unsigned int *nservers, unsigned int *nstats);
 353
 354 #endif
 355