Skip to content

Key-Value Database (KVDB)

Data Structures

Name
struct hse_mclass_info
Media class information.
struct hse_kvdb
Opaque structure, a pointer to which is a handle to an HSE key-value database (KVDB).

Types

Name
enum hse_mclass { HSE_MCLASS_CAPACITY = 0, HSE_MCLASS_STAGING = 1, HSE_MCLASS_PMEM = 2}
Media classes.

Functions

Name
hse_err_t hse_kvdb_attach(const char * kvdb_home_tgt, const char * kvdb_home_src, const char * paths[HSE_MCLASS_COUNT])
Attach a new KVDB to a snapshot/copy of the media class paths from kvdb_home_src.
hse_err_t hse_kvdb_close(struct hse_kvdb * kvdb)
Close a KVDB.
hse_err_t hse_kvdb_create(const char * kvdb_home, size_t paramc, const char *const * paramv)
Create a KVDB.
hse_err_t hse_kvdb_drop(const char * kvdb_home)
Drop a KVDB.
const char * hse_kvdb_home_get(struct hse_kvdb * kvdb)
Get the KVDB home.
hse_err_t hse_kvdb_kvs_names_get(struct hse_kvdb * kvdb, size_t * namec, char *** namev)
Get the names of the KVSs within the given KVDB.
void hse_kvdb_kvs_names_free(struct hse_kvdb * kvdb, char ** namev)
Free the names collection obtained through hse_kvdb_kvs_names_get().
hse_err_t hse_kvdb_mclass_info_get(struct hse_kvdb * kvdb, enum hse_mclass mclass, struct hse_mclass_info * info)
Get media class information from a KVDB.
bool hse_kvdb_mclass_is_configured(struct hse_kvdb * kvdb, enum hse_mclass mclass)
Check if a media class is configured for a KVDB.
hse_err_t hse_kvdb_mclass_reconfigure(const char * kvdb_home, enum hse_mclass mclass, const char * path)
Reconfigure a media class storage path for an existing offline KVDB.
hse_err_t hse_kvdb_open(const char * kvdb_home, size_t paramc, const char const * paramv, struct hse_kvdb * kvdb)
Open a KVDB.
hse_err_t hse_kvdb_param_get(struct hse_kvdb * kvdb, const char * param, char * buf, size_t buf_sz, size_t * needed_sz)
Get KVDB parameter.
hse_err_t hse_kvdb_storage_add(const char * kvdb_home, size_t paramc, const char *const * paramv)
Add new media class storage to an existing offline KVDB.
hse_err_t hse_kvdb_sync(struct hse_kvdb * kvdb, unsigned int flags)
Sync data in all of the referenced KVDB's KVSs to stable media.
const char * hse_mclass_name_get(enum hse_mclass mclass)
Get the name of a media class.

Defines

Name
HSE_MCLASS_BASE
HSE_MCLASS_MAX
HSE_MCLASS_COUNT
HSE_MCLASS_CAPACITY_NAME
HSE_MCLASS_STAGING_NAME
HSE_MCLASS_PMEM_NAME

Types Documentation

enum hse_mclass

Enumerator Value Description
HSE_MCLASS_CAPACITY 0
HSE_MCLASS_STAGING 1
HSE_MCLASS_PMEM 2

Media classes.

Functions Documentation

function hse_kvdb_attach

hse_err_t hse_kvdb_attach(
    const char * kvdb_home_tgt,
    const char * kvdb_home_src,
    const char * paths[HSE_MCLASS_COUNT]
)

Attach a new KVDB to a snapshot/copy of the media class paths from kvdb_home_src.

Parameters:

  • kvdb_home_tgt KVDB home directory for the attach target.
  • kvdb_home_src KVDB home directory for the attach source.
  • paths A snapshot/copy of the media class paths from the attach source.

Return: Error status.

Note: This function is not thread safe.

Remark:

  • kvdb_home_tgt and kvdb_home_src must not be NULL.
  • kvdb_home_src must be offline for attach.
  • A snapshot/copy of all the configured media class paths must be provided in paths.

function hse_kvdb_close

hse_err_t hse_kvdb_close(
    struct hse_kvdb * kvdb
)

Close a KVDB.

Parameters:

Return: Error status.

Note: This function is not thread safe.

Warning: After invoking this function, calling any other KVDB functions will result in undefined behavior unless the KVDB is re-opened.

Remark: kvdb must not be NULL.

function hse_kvdb_create

hse_err_t hse_kvdb_create(
    const char * kvdb_home,
    size_t paramc,
    const char *const * paramv
)

Create a KVDB.

Parameters:

  • kvdb_home KVDB home directory.
  • paramc Number of configuration parameters in paramv.
  • paramv List of parameters in key=value format.

Return: Error status.

Remark:

  • kvdb_home must not be NULL.
  • kvdb_home must have a length > 0.
  • If paramc is > 0, then paramv cannot be NULL.

function hse_kvdb_drop

hse_err_t hse_kvdb_drop(
    const char * kvdb_home
)

Drop a KVDB.

Parameters:

  • kvdb_home KVDB home directory.

Return: Error status.

Warning: It is an error to call this function on a KVDB that is open.

Remark:

  • kvdb_home must not be NULL.
  • kvdb_home must have a length > 0.

function hse_kvdb_home_get

const char * hse_kvdb_home_get(
    struct hse_kvdb * kvdb
)

Get the KVDB home.

Parameters:

Returns:

  • NULL if given an invalid KVDB handle.

Return: KVDB home.

Note: This function is thread safe.

Remark: kvdb must not be NULL.

function hse_kvdb_kvs_names_get

hse_err_t hse_kvdb_kvs_names_get(
    struct hse_kvdb * kvdb,
    size_t * namec,
    char *** namev
)

Get the names of the KVSs within the given KVDB.

Parameters:

  • kvdb KVDB handle from hse_kvdb_open().
  • namec Number of KVSs in the KVDB.
  • namev Vector of KVSs allocated by the function.

Return: Error status.

Note: This function is thread safe.

Remark:

  • kvdb must not be NULL.
  • namev must not be NULL.

Key-value stores (KVSs) are opened by name. This function allocates a vector of allocated strings, each containing the NULL-terminated name of a KVS. The memory must be freed via hse_kvdb_kvs_names_free().

Example Usage:

int namec;
char **namev;
hse_err_t err;

err = hse_kvdb_kvs_names_get(kvdb, &namec, &namev);
if (!err) {
    for (int i = 0; i < namec; i++)
        printf("%s\n", namev[i]);
}
hse_kvdb_kvs_names_free(namev);

Filename: .c

function hse_kvdb_kvs_names_free

void hse_kvdb_kvs_names_free(
    struct hse_kvdb * kvdb,
    char ** namev
)

Free the names collection obtained through hse_kvdb_kvs_names_get().

Parameters:

Note: This function is thread safe.

function hse_kvdb_mclass_info_get

hse_err_t hse_kvdb_mclass_info_get(
    struct hse_kvdb * kvdb,
    enum hse_mclass mclass,
    struct hse_mclass_info * info
)

Get media class information from a KVDB.

Parameters:

  • kvdb KVDB handle from hse_kvdb_open().
  • mclass Media class to query for.
  • info Media class information object.

Return: Error status.

Note: This function is thread safe.

Remark:

  • kvdb must not be NULL.
  • info must not be NULL.

function hse_kvdb_mclass_is_configured

bool hse_kvdb_mclass_is_configured(
    struct hse_kvdb * kvdb,
    enum hse_mclass mclass
)

Check if a media class is configured for a KVDB.

Parameters:

Returns:

  • false if kvdb or mclass is invalid.

Return: Whether or not mclass is configured.

Note: This function is thread safe.

Remark: kvdb must not be NULL.

function hse_kvdb_mclass_reconfigure

hse_err_t hse_kvdb_mclass_reconfigure(
    const char * kvdb_home,
    enum hse_mclass mclass,
    const char * path
)

Reconfigure a media class storage path for an existing offline KVDB.

Parameters:

  • kvdb_home KVDB home directory.
  • mclass Media class to reconfigure.
  • path New media class path.

Return: Error status.

Note: This function is not thread safe.

Remark: KVDB must be offline when reconfiguring a media class path.

function hse_kvdb_open

hse_err_t hse_kvdb_open(
    const char * kvdb_home,
    size_t paramc,
    const char *const * paramv,
    struct hse_kvdb ** kvdb
)

Open a KVDB.

Parameters:

  • kvdb_home KVDB home directory.
  • paramc Number of configuration parameters in paramv.
  • paramv List of parameters in key=value format.
  • kvdb Handle to access the opened KVDB.

Return: Error status.

Note: Only one KVDB can be open at any one time.

Remark:

  • The KVDB must have already been created.
  • kvdb_home must not be NULL.
  • kvdb_home must have a length > 0.
  • If paramc is > 0, then paramv cannot be NULL.
  • kvdb must not be NULL.

function hse_kvdb_param_get

hse_err_t hse_kvdb_param_get(
    struct hse_kvdb * kvdb,
    const char * param,
    char * buf,
    size_t buf_sz,
    size_t * needed_sz
)

Get KVDB parameter.

Parameters:

  • kvdb KVDB handle from hse_kvdb_open().
  • param Parameter name.
  • buf Buffer for writing stringified value of parameter.
  • buf_sz Size of buf.
  • needed_sz Needed size of buf.

Return: Error status.

Note: This function is thread safe.

Remark:

  • kvdb must not be NULL.
  • param must not be NULL.
  • param must be a valid parameter.

Puts the stringified version of the parameter value into buf. If buf_sz is NULL, then needed_sz will still be populated.

function hse_kvdb_storage_add

hse_err_t hse_kvdb_storage_add(
    const char * kvdb_home,
    size_t paramc,
    const char *const * paramv
)

Add new media class storage to an existing offline KVDB.

Parameters:

  • kvdb_home KVDB home directory.
  • paramc Number of configuration parameters in paramv.
  • paramv List of KVDB create-time parameters in key=value format.

Return: Error status.

Note: This function is not thread safe.

Remark:

  • kvdb_home must not be NULL.
  • KVDB must have already been created.
  • paramv must not be NULL.

function hse_kvdb_sync

hse_err_t hse_kvdb_sync(
    struct hse_kvdb * kvdb,
    unsigned int flags
)

Sync data in all of the referenced KVDB's KVSs to stable media.

Parameters:

  • kvdb KVDB handle from hse_kvdb_open().
  • flags Flags for operation specialization.

Return: Error status.

Note: This function is thread safe.

Remark: kvdb must not be NULL.

Flags:

  • HSE_KVDB_SYNC_ASYNC - Return immediately after initiating operation instead of waiting for completion.

function hse_mclass_name_get

const char * hse_mclass_name_get(
    enum hse_mclass mclass
)

Get the name of a media class.

Parameters:

  • mclass Media class.

Return: Name of media class.

Note: This function is thread safe.

Macros Documentation

define HSE_MCLASS_BASE

#define HSE_MCLASS_BASE HSE_MCLASS_CAPACITY

Capacity media class.

define HSE_MCLASS_MAX

#define HSE_MCLASS_MAX HSE_MCLASS_PMEM

Staging media class.

define HSE_MCLASS_COUNT

#define HSE_MCLASS_COUNT ([HSE_MCLASS_MAX](/3.x/api/Modules/group__KVDB/#define-hse_mclass_max) + 1)

PMEM media class.

define HSE_MCLASS_CAPACITY_NAME

#define HSE_MCLASS_CAPACITY_NAME "capacity"

Capacity media class name.

define HSE_MCLASS_STAGING_NAME

#define HSE_MCLASS_STAGING_NAME "staging"

Staging media class name.

define HSE_MCLASS_PMEM_NAME

#define HSE_MCLASS_PMEM_NAME "pmem"

PMEM media class name.


Updated on 17 November 2022 at 15:11:02 CST