NAME
SYNOPSIS
DESCRIPTION
EXAMPLE
ERRORS
SEE ALSO

NAME

pmemkv_config - Configuration API for libpmemkv

SYNOPSIS

#include <libpmemkv.h>

pmemkv_config *pmemkv_config_new(void);
void pmemkv_config_delete(pmemkv_config *config);
int pmemkv_config_put_data(pmemkv_config *config, const char *key, const void *value,
			size_t value_size);
int pmemkv_config_put_object(pmemkv_config *config, const char *key, void *value,
			void (*deleter)(void *));
int pmemkv_config_put_object_cb(pmemkv_config *config, const char *key, void *value,
				void *(*getter)(void *), void (*deleter)(void *));
int pmemkv_config_put_uint64(pmemkv_config *config, const char *key, uint64_t value);
int pmemkv_config_put_int64(pmemkv_config *config, const char *key, int64_t value);
int pmemkv_config_put_string(pmemkv_config *config, const char *key, const char *value);
int pmemkv_config_get_data(pmemkv_config *config, const char *key, const void **value,
			size_t *value_size);
int pmemkv_config_get_object(pmemkv_config *config, const char *key, void **value);
int pmemkv_config_get_uint64(pmemkv_config *config, const char *key, uint64_t *value);
int pmemkv_config_get_int64(pmemkv_config *config, const char *key, int64_t *value);
int pmemkv_config_get_string(pmemkv_config *config, const char *key, const char **value);

pmemkv_comparator pmemkv_comparator_new(pmemkv_compare_function fn, const char name,
void arg);
void pmemkv_comparator_delete(pmemkv_comparator *comparator);

For general description of pmemkv and available engines see libpmemkv(7). For description of pmemkv core API see libpmemkv(3).

DESCRIPTION

pmemkv database is configured using pmemkv_config structure. It stores mappings of keys (null-terminated strings) to values. A value can be:

  • uint64_t
  • int64_t
  • c-style string
  • binary data
  • pointer to an object (with accompanying deleter function)

It also delivers methods to store and read configuration items provided by a user. Once the configuration object is set (with all required parameters), it can be passed to pmemkv_open() method.

List of options which are required by pmemkv database is specific to an engine. Every engine has documented all supported config parameters (please see libpmemkv(7) for details).

pmemkv_config *pmemkv_config_new(void);
Creates an instance of configuration for pmemkv database.

On failure, NULL is returned.

void pmemkv_config_delete(pmemkv_config *config);
Deletes pmemkv_config. Should be called ONLY for configs which were not passed to pmemkv_open (as this function moves ownership of the config to the database).
int pmemkv_config_put_uint64(pmemkv_config *config, const char *key, uint64_t value);

Puts uint64_t value value to pmemkv_config at key key.

int pmemkv_config_put_int64(pmemkv_config *config, const char *key, int64_t value);

Puts int64_t value value to pmemkv_config at key key.

int pmemkv_config_put_string(pmemkv_config *config, const char *key, const char *value);

Puts null-terminated string to pmemkv_config. The string is copied to the config.

int pmemkv_config_put_data(pmemkv_config *config, const char *key, const void *value, size_t value_size);

Puts copy of binary data pointed by value to pmemkv_config. value_size specifies size of the data.

int pmemkv_config_put_object(pmemkv_config *config, const char *key, void *value, void (*deleter)(void *));

Puts value to pmemkv_config. value can point to arbitrary object. deleter parameter specifies function which will be called for value when the config is destroyed (using pmemkv_config_delete).

int pmemkv_config_put_object_cb(pmemkv_config *config, const char *key, void *value, void *(*getter)(void *), void (*deleter)(void *));

Extended version of pmemkv_config_put_object. It accepts one additional argument - a getter callback. This callback interprets the custom object (value) and returns a pointer which is expected by pmemkv.

Calling pmemkv_config_put_object_cb with getter implemented as:

void *getter(void *arg) { return arg; }

is equivalent to calling pmemkv_config_put_object.

int pmemkv_config_get_uint64(pmemkv_config *config, const char *key, uint64_t *value);

Gets value of a config item with key key. Value is copied to variable pointed by value.

int pmemkv_config_get_int64(pmemkv_config *config, const char *key, int64_t *value);

Gets value of a config item with key key. Value is copied to variable pointed by value.

int pmemkv_config_get_string(pmemkv_config *config, const char *key, const char **value);

Gets pointer to a null-terminated string. The string is not copied. After successful call value points to string stored in pmemkv_config.

int pmemkv_config_get_data(pmemkv_config *config, const char *key, const void **value, size_t *value_size);

Gets pointer to binary data. Data is not copied. After successful call *value points to data stored in pmemkv_config and value_size holds size of the data.

int pmemkv_config_get_object(pmemkv_config *config, const char *key, const void **value);

Gets pointer to an object. After successful call, *value points to the object.

Config items stored in pmemkv_config, which were put using a specific function can be obtained only using corresponding pmemkv_config_get_ function (for example, config items put using pmemkv_config_put_object can only be obtained using pmemkv_config_get_object). Exception from this rule are functions for uint64 and int64. If value put by pmemkv_config_put_int64 is in uint64_t range it can be obtained using pmemkv_config_get_uint64 and vice versa.

pmemkv_comparator *pmemkv_comparator_new(pmemkv_compare_function *fn, const char *name, void *arg);

Creates instance of a comparator object. Accepts comparison function fn, name and arg. In case of persistent engines, nameis stored within the engine. Attempt to open a database which was createad with different comparator of different name will fail with PMEMKV_STATUS_COMPARATOR_MISMATCH.arg` is saved in the comparator and passed to a comparison function on each invocation.

Neither fn nor name can be NULL.

fn should perform a three-way comparison. Return values:

  • negative value if the first key is less than the second one
  • zero if both keys are the same
  • positive value if the first key is greater than the second one

The comparison function should be thread safe - it can be called from multiple threads.

On failure, NULL is returned.

void pmemkv_comparator_delete(pmemkv_comparator *comparator);

Removes the comparator object. Should be called ONLY for comparators which were not put to config (as config takes ownership of the comparator).

To set a comparator for the database use pmemkv_config_put_object:

pmemkv_comparator *cmp = pmemkv_comparator_new(&compare_fn, "my_comparator", NULL);

pmemkv_config_put_object(cfg, "comparator", cmp, (void ()(void )) & pmemkv_comparator_delete);

ERRORS

Each function, except for pmemkv_config_new() and pmemkv_config_delete(), returns status. Possible return values are:

  • PMEMKV_STATUS_OK – no error
  • PMEMKV_STATUS_UNKNOWN_ERROR – unknown error
  • PMEMKV_STATUS_NOT_FOUND – record (or config item) not found
  • PMEMKV_STATUS_CONFIG_PARSING_ERROR – parsing data to config failed
  • PMEMKV_STATUS_CONFIG_TYPE_ERROR – config item has different type than expected

EXAMPLE

The following example is taken from examples/pmemkv_config_c/pmemkv_config.c.

// SPDX-License-Identifier: BSD-3-Clause
#include <assert.h>
#include <libpmemkv.h>
#include <libpmemkv_json_config.h>
#include <stdlib.h>
#include <string.h>

/* deleter for int pointer */
void free_int_ptr(void *ptr)
{
	free(ptr);
}

int main()
{
pmemkv_config *config = pmemkv_config_new();
assert(config != NULL);


<span style="color:#75715e">/* Put int64_t value */</span>
<span style="color:#66d9ef">int</span> status <span style="color:#f92672">=</span> pmemkv_config_put_int64(config, <span style="color:#e6db74">&#34;size&#34;</span>, <span style="color:#ae81ff">1073741824</span>);
assert(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);

<span style="color:#66d9ef">char</span> buffer[] <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;ABC&#34;</span>;

<span style="color:#75715e">/* Put binary data stored in buffer */</span>
status <span style="color:#f92672">=</span> pmemkv_config_put_data(config, <span style="color:#e6db74">&#34;binary&#34;</span>, buffer, <span style="color:#ae81ff">3</span>);
assert(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);

<span style="color:#66d9ef">const</span> <span style="color:#66d9ef">void</span> <span style="color:#f92672">*</span>data;
size_t data_size;

<span style="color:#75715e">/* Get pointer to binary data stored in config */</span>
status <span style="color:#f92672">=</span> pmemkv_config_get_data(config, <span style="color:#e6db74">&#34;binary&#34;</span>, <span style="color:#f92672">&amp;</span>data, <span style="color:#f92672">&amp;</span>data_size);
assert(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
assert(data_size <span style="color:#f92672">==</span> <span style="color:#ae81ff">3</span>);
assert(((<span style="color:#66d9ef">const</span> <span style="color:#66d9ef">char</span> <span style="color:#f92672">*</span>)data)[<span style="color:#ae81ff">0</span>] <span style="color:#f92672">==</span> <span style="color:#e6db74">&#39;A&#39;</span>);

<span style="color:#66d9ef">int</span> <span style="color:#f92672">*</span>int_ptr <span style="color:#f92672">=</span> malloc(<span style="color:#66d9ef">sizeof</span>(<span style="color:#66d9ef">int</span>));
assert(int_ptr <span style="color:#f92672">!=</span> NULL);
<span style="color:#f92672">*</span>int_ptr <span style="color:#f92672">=</span> <span style="color:#ae81ff">10</span>;

<span style="color:#75715e">/* Put pointer to dynamically allocated object, free_int_ptr is called on



 * pmemkv_config_delete */
status = pmemkv_config_put_object(config, "int_ptr", int_ptr, &free_int_ptr);
assert(status == PMEMKV_STATUS_OK);


<span style="color:#66d9ef">int</span> <span style="color:#f92672">*</span>get_int_ptr;

<span style="color:#75715e">/* Get pointer to object stored in config */</span>
status <span style="color:#f92672">=</span> pmemkv_config_get_object(config, <span style="color:#e6db74">&#34;int_ptr&#34;</span>, (<span style="color:#66d9ef">void</span> <span style="color:#f92672">**</span>)<span style="color:#f92672">&amp;</span>get_int_ptr);
assert(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
assert(<span style="color:#f92672">*</span>get_int_ptr <span style="color:#f92672">==</span> <span style="color:#ae81ff">10</span>);

pmemkv_config_delete(config);

pmemkv_config <span style="color:#f92672">*</span>config_from_json <span style="color:#f92672">=</span> pmemkv_config_new();
assert(config_from_json <span style="color:#f92672">!=</span> NULL);

<span style="color:#75715e">/* Parse JSON and put all items found into config_from_json */</span>
status <span style="color:#f92672">=</span> pmemkv_config_from_json(config_from_json, <span style="color:#e6db74">&#34;{</span><span style="color:#ae81ff">\&#34;</span><span style="color:#e6db74">path</span><span style="color:#ae81ff">\&#34;</span><span style="color:#e6db74">:</span><span style="color:#ae81ff">\&#34;</span><span style="color:#e6db74">/dev/shm</span><span style="color:#ae81ff">\&#34;</span><span style="color:#e6db74">,\



 &#34;size&#34;:1073741824,

 &#34;subconfig&#34;:{

 &#34;size&#34;:1073741824

 }

 }");
assert(status == PMEMKV_STATUS_OK);


<span style="color:#66d9ef">const</span> <span style="color:#66d9ef">char</span> <span style="color:#f92672">*</span>path;
status <span style="color:#f92672">=</span> pmemkv_config_get_string(config_from_json, <span style="color:#e6db74">&#34;path&#34;</span>, <span style="color:#f92672">&amp;</span>path);
assert(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
assert(strcmp(path, <span style="color:#e6db74">&#34;/dev/shm&#34;</span>) <span style="color:#f92672">==</span> <span style="color:#ae81ff">0</span>);

pmemkv_config <span style="color:#f92672">*</span>subconfig;

<span style="color:#75715e">/* Get pointer to nested configuration &#34;subconfig&#34; */</span>
status <span style="color:#f92672">=</span> pmemkv_config_get_object(config_from_json, <span style="color:#e6db74">&#34;subconfig&#34;</span>,
				  (<span style="color:#66d9ef">void</span> <span style="color:#f92672">**</span>)<span style="color:#f92672">&amp;</span>subconfig);
assert(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);

size_t sub_size;
status <span style="color:#f92672">=</span> pmemkv_config_get_uint64(subconfig, <span style="color:#e6db74">&#34;size&#34;</span>, <span style="color:#f92672">&amp;</span>sub_size);
assert(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
assert(sub_size <span style="color:#f92672">==</span> <span style="color:#ae81ff">1073741824</span>);

pmemkv_config_delete(config_from_json);

<span style="color:#66d9ef">return</span> <span style="color:#ae81ff">0</span>;



}

SEE ALSO

libpmemkv(7), libpmemkv(3) , libpmemkv_json_config(3) and https://pmem.io

The contents of this web site and the associated GitHub repositories are BSD-licensed open source.