Ubuntu Manpages

pmemkv_config

Configuration API for libpmemkv

#include <libpmemkv.h>
pmemkv_config *pmemkv_config_new(void);
void pmemkv_config_delete(pmemkv_config *config);
int pmemkv_config_put_size(pmemkv_config *config, uint64_t value);
int pmemkv_config_put_path(pmemkv_config *config, const char *value);
int **deprecated** pmemkv_config_put_force_create(pmemkv_config *config,
                               bool value);
int pmemkv_config_put_create_or_error_if_exists(pmemkv_config *config, bool value);
int pmemkv_config_put_create_if_missing(pmemkv_config *config, bool value)
int pmemkv_config_put_comparator(pmemkv_config *config, pmemkv_comparator *comparator);
int pmemkv_config_put_oid(pmemkv_config *config, PMEMoid *oid);
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).

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).

Creates an instance of configuration for pmemkv database. On failure, NULL is returned.
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).
Puts value to a config at key size, it’s required when creating new database pool. This function provides type safety for size parameter.
Puts value to a config at key path. It’s a path to a database file or to a poolset file (see poolset(5) for details), to open or create. Note that when using poolset file, size should be 0. This function provides type safety for path parameter.
It is deprecated and kept for compatibility. It’s an alias for pmemkv_config_put_create_or_error_if_exists - use it instead.
Puts value to a config at key create_or_error_if_exists. This flag is mutually exclusive with create_if_missing. It works only with engines supporting this flag and it means: If true: pmemkv creates the pool, unless it exists - then it fails. If false: pmemkv opens the pool, unless the path does not exist - then it fails. False by default.
Puts value to a config at key create_if_missing. This flag is mutually exclusive with create_or_error_if_exists. It works only with engines supporting this flag and it means: If true: pmemkv tries to open the pool and if that doesn’t succeed it means there’s (most likely) no pool to use, so it tries to create it. If false: pmemkv opens the pool, unless the path does not exist - then it fails. False by default.
Puts comparator object to a config. To create an instance of pmemkv_comparator object, pmemkv_comparator_new() function should be used.
Puts PMEMoid object to a config (for details see libpmemkv(7)).
Puts uint64_t value value to pmemkv_config at key key.
Puts int64_t value value to pmemkv_config at key key.
Puts null-terminated string to pmemkv_config. The string is copied to the config.
Puts copy of binary data pointed by value to pmemkv_config. value_size specifies size of the data.
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).
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.

Gets value of a config item with key key. Value is copied to variable pointed by value.
Gets value of a config item with key key. Value is copied to variable pointed by value.
Gets pointer to a null-terminated string. The string is not copied. After successful call value points to string stored in pmemkv_config.
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.
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.

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.

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);

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

The following examples are taken from examples/pmemkv_config_c directory.

Usage of basic config functions to set parameters based on their functionalities, e.g. pmemkv_config_put_path() or pmemkv_config_put_size().

#include <assert.h>
#include <libpmemkv.h>
#include <libpmemobj/pool_base.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#define ASSERT(expr)                                                                     \
    do {                                                                             \
        if (!(expr))                                                             \
            puts(pmemkv_errormsg());                                         \
        assert(expr);                                                            \
    } while (0)
static const uint64_t SIZE = 1024UL * 1024UL * 1024UL;
int key_length_compare(const char *key1, size_t keybytes1, const char *key2,
               size_t keybytes2, void *arg)
{
    if (keybytes2 < keybytes1)
        return -1;
    else if (keybytes2 > keybytes1)
        return 1;
    else
        return 0;
}
int main(int argc, char *argv[])
{
    if (argc < 2) {
        fprintf(stderr, "Usage: %s file\n", argv[0]);
        exit(1);
    }
    /* Create config */
    pmemkv_config *config = pmemkv_config_new();
    ASSERT(config != NULL);
    /* Add path parameter to config. Meaning of this is dependent on chosen engine.
     *  E.g. if config is used with cmap engine,
     *  it is a path to a database file or to a poolset file. However for
     *  vcmap it is a path to an existing directory */
    int status = pmemkv_config_put_path(config, argv[1]);
    ASSERT(status == PMEMKV_STATUS_OK);
    /* Specifies size of the database */
    status = pmemkv_config_put_size(config, SIZE);
    ASSERT(status == PMEMKV_STATUS_OK);
    /* Specifies value of create_if_missing flag.
     * Alternatively, another flag - 'create_or_error_if_exists' can be set using:
     * `pmemkv_config_put_create_or_error_if_exists`
     * For differences between the two, see manpage libpmemkv(7). */
    status = pmemkv_config_put_create_if_missing(config, true);
    ASSERT(status == PMEMKV_STATUS_OK);
    /* Specifies comparator used by the engine */
    pmemkv_comparator *cmp =
        pmemkv_comparator_new(&key_length_compare, "key_length_compare", NULL);
    ASSERT(cmp != NULL);
    status = pmemkv_config_put_comparator(config, cmp);
    ASSERT(status == PMEMKV_STATUS_OK);
    /* Adds pointer to oid (for details see libpmemkv(7)) to the config */
    PMEMoid oid;
    status = pmemkv_config_put_oid(config, &oid);
    ASSERT(status == PMEMKV_STATUS_OK);
    pmemkv_config_delete(config);
    return 0;
}

Usage of config functions to set and get data based on their data type, e.g. pmemkv_config_put_int64() or pmemkv_config_put_object().

#include <assert.h>
#include <libpmemkv.h>
#include <libpmemkv_json_config.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#define ASSERT(expr)                                                                     \
    do {                                                                             \
        if (!(expr))                                                             \
            puts(pmemkv_errormsg());                                         \
        assert(expr);                                                            \
    } while (0)
/* deleter for int pointer */
void free_int_ptr(void *ptr)
{
    free(ptr);
}
int main()
{
    pmemkv_config *config = pmemkv_config_new();
    ASSERT(config != NULL);
    /* Put int64_t value */
    int status = pmemkv_config_put_int64(config, "size", 1073741824);
    ASSERT(status == PMEMKV_STATUS_OK);
    char buffer[] = "ABC";
    /* Put binary data stored in buffer */
    status = pmemkv_config_put_data(config, "binary", buffer, 3);
    ASSERT(status == PMEMKV_STATUS_OK);
    const void *data;
    size_t data_size;
    /* Get pointer to binary data stored in config */
    status = pmemkv_config_get_data(config, "binary", &data, &data_size);
    ASSERT(status == PMEMKV_STATUS_OK);
    ASSERT(data_size == 3);
    ASSERT(((const char *)data)[0] == 'A');
    int *int_ptr = malloc(sizeof(int));
    ASSERT(int_ptr != NULL);
    *int_ptr = 10;
    /* 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);
    int *get_int_ptr;
    /* Get pointer to object stored in config */
    status = pmemkv_config_get_object(config, "int_ptr", (void **)&get_int_ptr);
    ASSERT(status == PMEMKV_STATUS_OK);
    ASSERT(*get_int_ptr == 10);
    pmemkv_config_delete(config);
    pmemkv_config *config_from_json = pmemkv_config_new();
    ASSERT(config_from_json != NULL);
    /* Parse JSON and put all items found into config_from_json */
    status = pmemkv_config_from_json(config_from_json, "{\"path\":\"/dev/shm\",\
         \"size\":1073741824,\
         \"subconfig\":{\
            \"size\":1073741824\
            }\
        }");
    ASSERT(status == PMEMKV_STATUS_OK);
    const char *path;
    status = pmemkv_config_get_string(config_from_json, "path", &path);
    ASSERT(status == PMEMKV_STATUS_OK);
    ASSERT(strcmp(path, "/dev/shm") == 0);
    pmemkv_config *subconfig;
    /* Get pointer to nested configuration "subconfig" */
    status = pmemkv_config_get_object(config_from_json, "subconfig",
                      (void **)&subconfig);
    ASSERT(status == PMEMKV_STATUS_OK);
    size_t sub_size;
    status = pmemkv_config_get_uint64(subconfig, "size", &sub_size);
    ASSERT(status == PMEMKV_STATUS_OK);
    ASSERT(sub_size == 1073741824);
    pmemkv_config_delete(config_from_json);
    return 0;
}

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