Cursors

Data Structures

	Name
struct	hse_kvs_cursor Opaque structure, a pointer to which is a handle to a cursor within a KVS.

Functions

	Name
hse_err_t	hse_kvs_cursor_create(struct hse_kvs * kvs, unsigned int flags, struct hse_kvdb_txn * txn, const void * filter, size_t filter_len, struct hse_kvs_cursor ** cursor) Creates a cursor used to iterate over key-value pairs in a KVS.
hse_err_t	hse_kvs_cursor_destroy(struct hse_kvs_cursor * cursor) Destroy cursor.
hse_err_t	hse_kvs_cursor_read(struct hse_kvs_cursor * cursor, unsigned int flags, const void *key, size_t key_len, const void** val, size_t * val_len, bool * eof) Iteratively access the elements pointed to by the cursor.
hse_err_t	hse_kvs_cursor_read_copy(struct hse_kvs_cursor * cursor, unsigned int flags, void * keybuf, size_t keybuf_sz, size_t * key_len, void * valbuf, size_t valbuf_sz, size_t * val_len, bool * eof) Iteratively access the elements pointed to by the cursor.
hse_err_t	hse_kvs_cursor_seek(struct hse_kvs_cursor * cursor, unsigned int flags, const void * key, size_t key_len, const void ** found, size_t * found_len) Move the cursor to point at the key-value pair at or closest to `key`.
hse_err_t	hse_kvs_cursor_seek_range(struct hse_kvs_cursor * cursor, unsigned int flags, const void * filt_min, size_t filt_min_len, const void * filt_max, size_t filt_max_len, const void ** found, size_t * found_len) Move the cursor to the closest match to key, gated by the given filter.
hse_err_t	hse_kvs_cursor_update_view(struct hse_kvs_cursor * cursor, unsigned int flags) Update a the cursor view.

Detailed Description

See the concepts and best practices sections on https://hse-project.github.io.

Functions Documentation

function hse_kvs_cursor_create

hse_err_t hse_kvs_cursor_create(
    struct hse_kvs * kvs,
    unsigned int flags,
    struct hse_kvdb_txn * txn,
    const void * filter,
    size_t filter_len,
    struct hse_kvs_cursor ** cursor
)

Creates a cursor used to iterate over key-value pairs in a KVS.

Parameters:

kvs KVS to iterate over, handle from hse_kvdb_kvs_open().
flags Flags for operation specialization.
txn Transaction context (optional).
filter Iteration limited to keys matching this prefix filter (optional).
filter_len Length of filter (optional).
cursor Cursor handle.

Return: Error status

Note: This function is thread safe.

Remark:

kvs must not be NULL.
cursor must not be NULL.

Non-transactional cursors:

If txn is NULL, a non-transactional cursor is created. Non-transactional cursors have an ephemeral snapshot view of the KVS at the time it the cursor is created. The snapshot view is maintained for the life of the cursor. Writes to the KVS (put, deletes, etc.) made after the cursor is created will not be visible to the cursor unless hse_kvs_cursor_update_view() is used to obtain a more recent snapshot view. Non-transactional cursors can be used on transactional and non-transactional KVSs.

Transactional cursors:

If txn is not NULL, it must be a valid transaction handle or undefined behavior will result. If it is a valid handle to a transaction in the ACTIVE state, a transactional cursor is created. A transaction cursor's view includes the transaction's writes overlaid on the transaction's ephemeral snapshot view of the KVS. If the transaction is committed or aborted before the cursor is destroyed, the cursor's view reverts to same snaphsot view the transaction had when first became active. The cursor will no longer be able to see the transaction's writes. Calling hse_kvs_cursor_update_view() on a transactional cursor is a no-op and has no effect on the cursor's view. Transactional cursors can only be used on transactional KVSs.

Prefix vs non-prefix cursors:

Parameters filter and filter_len can be used to iterate over the subset of keys in the KVS whose first filter_len bytes match the filter_len bytes pointed to by filter.

A prefix cursor is created when:

KVS was created with pfx_len > 0 (i.e., it is a prefix KVS), and
filter != NULL and filter_len >= pfx_len.

Otherwise, a non-prefix cursor is created.

Applications should arrange their key-value data to avoid the need for non-prefix cursors as they are significantly slower and more resource-intensive than prefix cursors. Note that simply using a filter doesn't create a prefix cursor – it must meet the two conditions listed above.

Flags:

HSE_CURSOR_CREATE_REV - Iterate in reverse lexicographical order.

function hse_kvs_cursor_destroy

hse_err_t hse_kvs_cursor_destroy(
    struct hse_kvs_cursor * cursor
)

Destroy cursor.

Parameters:

cursor Cursor handle from hse_kvs_cursor_create().

Return: Error status.

Note: Cursor objects are not thread safe.

Warning: After invoking this function, calling any other cursor functions with this handle will result in undefined behavior.

Remark: cursor must not be NULL.

function hse_kvs_cursor_read

hse_err_t hse_kvs_cursor_read(
    struct hse_kvs_cursor * cursor,
    unsigned int flags,
    const void ** key,
    size_t * key_len,
    const void ** val,
    size_t * val_len,
    bool * eof
)

Iteratively access the elements pointed to by the cursor.

Parameters:

cursor Cursor handle from hse_kvs_cursor_create().
flags Flags for operation specialization.
key Next key in sequence.
key_len Length of key.
val Next value in sequence.
val_len Length of val.
eof If true, no more key-value pairs in sequence.

Return: Error status

Note:

If the cursor is at EOF, attempts to read from it will not change the state of the cursor.
Cursor objects are not thread safe.

Remark:

cursor must not be NULL.
key must not be NULL.
key_len must not be NULL.
val must not be NULL.
val_len must not be NULL.
eof must not be NULL.

Read a key-value pair from the cursor, advancing the cursor past its current location. If the argument val is NULL, only the key is read.

Flags:

0 - Reserved for future use.

function hse_kvs_cursor_read_copy

hse_err_t hse_kvs_cursor_read_copy(
    struct hse_kvs_cursor * cursor,
    unsigned int flags,
    void * keybuf,
    size_t keybuf_sz,
    size_t * key_len,
    void * valbuf,
    size_t valbuf_sz,
    size_t * val_len,
    bool * eof
)

Iteratively access the elements pointed to by the cursor.

Parameters:

cursor Cursor handle from hse_kvs_cursor_create().
flags Flags for operation specialization.
keybuf Buffer into which the next key will be copied.
keybuf_sz Size of keybuf.
key_len Length of the key.
valbuf Buffer into which the next key's value will be copied.
valbuf_sz Size of valbuf
val_len Length of val.
eof If true, no more key-value pairs in sequence.

Return: Error status

Note:

If the cursor is at EOF, attempts to read from it will not change the state of the cursor.
Cursor objects are not thread safe.

Remark:

cursor must not be NULL.
key must not be NULL.
key_len must not be NULL.
val must not be NULL.
val_len must not be NULL.
eof must not be NULL.

Read a key-value pair from the cursor, advancing the cursor past its current location. The key-value pair will be copied into the user's buffer(s). If the argument valbuf is NULL, only the key is read.

Flags:

0 - Reserved for future use.

function hse_kvs_cursor_seek

hse_err_t hse_kvs_cursor_seek(
    struct hse_kvs_cursor * cursor,
    unsigned int flags,
    const void * key,
    size_t key_len,
    const void ** found,
    size_t * found_len
)

Move the cursor to point at the key-value pair at or closest to key.

Parameters:

cursor Cursor handle from hse_kvs_cursor_create().
flags Flags for operation specialization.
key Key to find.
key_len Length of key.
found If non-NULL, referent point to next key in sequence (optional).
found_len If found is non-NULL, referent is length of found key.

Return: Error status.

Note: Cursor objects are not thread safe.

Remark: cursor must not be NULL.

The next hse_kvs_cursor_read() will start at this point. Both found and found_len must be non-NULL for that functionality to work.

Flags:

0 - Reserved for future use.

function hse_kvs_cursor_seek_range

hse_err_t hse_kvs_cursor_seek_range(
    struct hse_kvs_cursor * cursor,
    unsigned int flags,
    const void * filt_min,
    size_t filt_min_len,
    const void * filt_max,
    size_t filt_max_len,
    const void ** found,
    size_t * found_len
)

Move the cursor to the closest match to key, gated by the given filter.

Parameters:

cursor Cursor handle from hse_kvs_cursor_create().
flags Flags for operation specialization.
filt_min Filter minimum.
filt_min_len Length of filt_min.
filt_max Filter maximum.
filt_max_len Length of filt_max.
found If non-NULL, referent points to next key in sequence (optional).
found_len If non-NULL, referent is length of found key (optional).

Return: Error status.

Note:

This is only supported for forward cursors.
Cursor objects are not thread safe.

Remark: cursor must not be NULL.

Keys read from this cursor will belong to the closed interval defined by the given filter: [filt_min, filt_max]. For KVSs storing segmented keys, performance will be enhanced when filt_min_len and filt_max_len are greater than or equal to the KVS key prefix length. Both found and found_len must be non-NULL for that functionality to work.

Flags:

0 - Reserved for future use.

function hse_kvs_cursor_update_view

hse_err_t hse_kvs_cursor_update_view(
    struct hse_kvs_cursor * cursor,
    unsigned int flags
)

Update a the cursor view.

Parameters:

cursor Cursor handle from hse_kvs_cursor_create().
flags Flags for operation specialization.

Return: Error status.

Note: Cursor objects are not thread safe.

Remark: cursor must not be NULL.

This operation updates the snapshot view of a non-transaction cursor. It is a no-op on transaction cursors.

Flags:

0 - Reserved for future use.

Updated on 17 November 2022 at 15:10:57 CST