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_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_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_close

hse_err_t hse_kvdb_close(
    struct hse_kvdb * kvdb
)

Close a KVDB.

Parameters:

• kvdb KVDB handle from hse_kvdb_open().

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.

Note: This function is not thread safe.

Remark: kvdb_home must not 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.

Note: This function is not thread safe.

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

Remark: kvdb_home must not be NULL.

function hse_kvdb_home_get

const char * hse_kvdb_home_get(
    struct hse_kvdb * kvdb
)

Get the KVDB home.

Parameters:

• kvdb KVDB handle from hse_kvdb_open().

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:

• kvdb KVDB handle from hse_kvdb_open().
• namev Vector of KVS names that hse_kvdb_kvs_names_get() output.

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:

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

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_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: This function is not thread safe.

Remark:

• The KVDB must have already been created.
• kvdb_home must not 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.
• KVBD 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](/2.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:10:57 CST