C API Documentation

allocator.h

Typedefs

typedef struct yk_allocator yk_allocator_t: Memory allocator definition. Custom allocators may be used for certain backends such as map.

typedef void (*yk_allocator_init_fn)(yk_allocator_t*, const char*): Type of functions used to initialize an allocator object.

struct yk_allocator

#include <allocator.h>

Memory allocator definition. Custom allocators may be used for certain backends such as map.

Public Members

void *context

void *(*allocate)(void *context, size_t item_size, size_t count)

void (*deallocate)(void *context, void *address, size_t item_size, size_t count)

void (*finalize)(void *context)

bulk-cache.h

Typedefs

typedef struct yk_buffer *yk_buffer_t

typedef struct yk_bulk_cache *yk_bulk_cache_t

struct yk_buffer

Public Members

size_t size

hg_uint8_t mode

char *data

hg_bulk_t bulk

struct yk_bulk_cache

Public Members

void *(*init)(margo_instance_id mid, const char *config)

void (*finalize)(void *cache)

yk_buffer_t (*get)(void *cache, size_t size, hg_uint8_t mode)

void (*release)(void *cache, yk_buffer_t entry)

client.h

Defines

YOKAN_CLIENT_NULL

Typedefs

typedef struct yk_client *yk_client_t

Functions

yk_return_t yk_client_init(margo_instance_id mid, yk_client_t *client)

Creates a YOKAN client.

Parameters

mid – [in] Margo instance
client – [out] YOKAN client

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_client_finalize(yk_client_t client)

Finalizes a YOKAN client.

Parameters: client – [in] YOKAN client to finalize
Returns: YOKAN_SUCCESS or error code defined in common.h

collection.h

Typedefs

typedef yk_return_t (*yk_document_callback_t)(void*, size_t, yk_id_t, const void*, size_t)

Type of callback used by the fetch and iter functions.

Param void*: User-provided arguments.
Param size_t: Iteration index.
Param yk_id_t: Record id
Param const: void* Document data.
Param size_t: Size of the document.
Return: YK_SUCCESS or other error code.

typedef yk_return_t (*yk_document_bulk_callback_t)(void*, size_t, size_t, hg_bulk_t, hg_addr_t, size_t)

Type of callback used by the fetch_bulk and iter_bulk functions. For fetch_bulk, the bulk handle will expose the count size_t document sizes followed by the actual documents. For iter_bulk, it will contain the count yk_id_t document IDs, then the sizes, then the documents.

Param void*: User-provided arguments.
Param size_t: Start iteration index.
Param size_t: Number of documents in the bulk.
Param hg_bulk_t: Bulk containing the documents.
Param hg_addr_t: Address the bulk originates from.
Param size_t: Total size of the memory exposed by the bulk handle.
Return: YK_SUCCESS or other error code.

typedef struct yk_doc_fetch_options yk_doc_fetch_options_t: Options to provide to yk_doc_fetch_multi.

typedef struct yk_doc_iter_options yk_doc_iter_options_t: Options to pass to yk_doc_iter.

Functions

yk_return_t yk_collection_create(yk_database_handle_t dbh, const char *name, int32_t mode)

Create a collection in the specified database.

Parameters

dbh – [in] Database handle
name – [in] Name of the collection (null-terminated)
mode – [in] Mode

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_collection_drop(yk_database_handle_t dbh, const char *collection, int32_t mode)

Erase the collection from the underlying database.

Parameters

dbh – [in] Database handle
collection – [in] Collection name (null-terminated)
mode – [in] Mode

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_collection_exists(yk_database_handle_t dbh, const char *collection, int32_t mode, uint8_t *flag)

Check if the collection exists in the underlying database.

Parameters

dbh – [in] Database handle
collection – [in] Collection name (null-terminated)
mode – [in] Mode
flag – [out] set to 1 if the collection exists, 0 otherwise

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_collection_size(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t *count)

Get the number of documents currently stored in the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [out] Number of documents stored

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_collection_last_id(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t *id)

Get the last document id of the collection. This value corresponds to the id of the next document that will be stored in the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
id – [out] Last document id

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_store(yk_database_handle_t dbh, const char *collection, int32_t mode, const void *document, size_t size, yk_id_t *id)

Store a document into the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
document – [in] Record to store
size – [in] Size of the document
id – [out] Resulting document id

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_store_multi(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const void *const *documents, const size_t *rsizes, yk_id_t *ids)

Store multiple documents into the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of documents to store
documents – [in] Array of documents
rsizes – [in] Array of document sizes
ids – [out] Resulting document ids

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_store_packed(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const void *documents, const size_t *rsizes, yk_id_t *ids)

Same as yk_doc_store_multi but the documents are packed contiguously in memory.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of documents to store
documents – [in] Packed documents
rsizes – [in] Array of document sizes
ids – [out] Resulting document ids

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_store_bulk(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const char *origin, hg_bulk_t data, size_t offset, size_t size, yk_id_t *ids)

Store a document using the low-level bulk handle. The payload is considered from offset to offset+size in the bulk handle. See src/client/doc_store.cpp for information on how data in this buffer should be structured.

Parameters

dbh – Database handle
collection – Collection
mode – Mode
count – Number of records
origin – Origin address
data – Bulk handle
offset – Offset in the bulk handle
size – Size of the payload
ids – Resulting document ids

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_load(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t id, void *data, size_t *size)

Load a document from the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
[int] – id Record id
data – [out] Buffer to load the document
size – [inout] Size of the buffer (in) / document (out)

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_load_multi(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const yk_id_t *ids, void *const *documents, size_t *rsizes)

Load multiple documents from the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of documents to store
ids – [in] Record ids
documents – [out] Array of documents
rsizes – [inout] Array of buffer/document sizes

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_load_packed(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const yk_id_t *ids, size_t rbufsize, void *documents, size_t *rsizes)

Same as yk_doc_load_multi but the documents are packed contiguously in memory.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of documents to store
ids – [in] Record ids
rbufsize – [in] Record buffer size
documents – [out] Packed documents
rsizes – [out] Array of document sizes

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_load_bulk(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const yk_id_t *ids, const char *origin, hg_bulk_t data, size_t offset, size_t size, bool packed)

Low-level load operation based on a bulk handle. This function will take the data in [offset, offset+size[ from the bulk handle and interpret it as follows:

The first count * sizeof(size_t) bytes store the document sizes.
The next N bytes store documents back to back, where N = sum of document sizes Origin represents the address of the process that created the bulk handle. If NULL, the bulk handle is considered to have been created by the calling process.

This function is useful in situation where a process received a bulk handle from another process and wants to forward it to an YOKAN provider.

Note: the “packed” argument is important. It specifies whether the process that created the bulk handle did so by exposing a single contiguous buffer in which packed documents are meant to be stored (in which case the document sizes do not matter as an input), or if individual buffers were exposed to hold each documents (in which case the document sizes do matter as an input).

Parameters

dbh – Database handle
collection – Collection name
mode – Mode
count – Number of documents
ids – Record ids
origin – Origin address
data – Bulk handle containing document sizes and data
offset – Offset in the bulk handle
size – Size of the bulk handle (from offset)
packed – Whether documents are packed

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_fetch(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t id, yk_document_callback_t cb, void *uargs)

Fetch a document from the collection, calling a function on the document when it is received. This function is a version of yk_doc_load that does not need to know the size of the document ahead of time.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
id – [in] Record id
cb – [in] Callback to call on the document
uargs – [in] Arguments for the callback

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_fetch_multi(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const yk_id_t *ids, yk_document_callback_t cb, void *uargs, const yk_doc_fetch_options_t *options)

Fetch documents from the collection, calling a function on the documents when they are received. This function is a version of yk_doc_load_multi that does not need to know the size of the document ahead of time.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of ids
ids – [in] Record ids
cb – [in] Callback to call on the document
uargs – [in] Arguments for the callback
options – [in] Extra options

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_fetch_bulk(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const yk_id_t *ids, yk_document_bulk_callback_t cb, void *uargs, const yk_doc_fetch_options_t *options)

Fetch documents from the collection, calling a function on the bulk handle containing the documents. This function will not pull the documents from the received bulk handle, leaving the caller an opportunity to forward it to another process.

The bulk handle received will contain count*size_t document sizes, followed by the actual documents.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of ids
ids – [in] Record ids
cb – [in] Callback to call on the document
uargs – [in] Arguments for the callback
options – [in] Extra options

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_length(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t id, size_t *size)

Get the size of a document from the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
[int] – id Record id
size – [out] Size document

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_length_multi(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const yk_id_t *ids, size_t *rsizes)

Get the size of multiple documents from the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of documents to store
ids – [in] Record ids
rsizes – [out] Array of document sizes

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_update(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t id, const void *document, size_t size)

Update a document from the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
id – [in] Record id
document – [in] New document content
size – [in] Size of the document

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_update_multi(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const yk_id_t *ids, const void *const *documents, const size_t *rsizes)

Update multiple documents.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of documents to update
ids – [in] Ids of the documents to update
documents – [in] Array of pointers to document data
rsizes – [in] Array of document sizes

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_update_packed(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const yk_id_t *ids, const void *documents, const size_t *rsizes)

Update multiple documents that are contiguous in memory.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of documents to update
ids – [in] Ids of the documents to update
documents – [in] Contiguous buffer of documents
rsizes – [in] Array of document sizes

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_update_bulk(yk_database_handle_t dbh, const char *name, int32_t mode, size_t count, const yk_id_t *ids, const char *origin, hg_bulk_t data, size_t offset, size_t size)

Low-level version of update that takes an already create bulk handle. The bulk handle is interpreted the same way as in yk_doc_store_bulk.

Parameters

dbh – Database handle
name – Collection name
mode – Mode
count – Number of documents
ids – Record ids
origin – Origin address
data – Bulk containing data
offset – Offset in the bulk in which the data is
size – Size of the bulk region (after offset)

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_erase(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t id)

Erase a document from the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
id – [in] Id of the document to erase

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_erase_multi(yk_database_handle_t dbh, const char *collection, int32_t mode, size_t count, const yk_id_t *ids)

Erase multiple documents from the collection.

Parameters

dbh – [in] Database handle
collection – [in] Collection
mode – [in] Mode
count – [in] Number of documents to erase
ids – [in] Ids of the documents to erase

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_list(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t start_id, const void *filter, size_t filter_size, size_t max, yk_id_t *ids, void *const *docs, size_t *doc_sizes)

List up to max documents starting at start_id Contrary to yk_list_keys and yk_list_keyvals, for which the filter is applied to the key, the filter here is applied to the document’s content. By default, the filter is ignored. If fewer than max documents are returned, the extra doc_sizes are set to YOKAN_NO_MORE_DOCS.

Important: start_id is inclusive, whether YOKAN_MODE_INCLUSIVE is set or not. To exclude it, simply start at start_id+1.

Parameters

dbh – [in] Database handle.
collection – [in] Collection
mode – [in] Mode
start_id – [in] Starting document id
filter – [in] Filter content
filter_size – [in] Filter size
max – [in] Maximum number of documents to return
ids – [out] Ids of the documents returned
docs – [out] Buffers in which to receive documents
doc_sizes – [inout] Buffers/document sizes

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_list_packed(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t start_id, const void *filter, size_t filter_size, size_t max, yk_id_t *ids, size_t bufsize, void *docs, size_t *doc_sizes)

Same as yk_doc_list but uses a single buffer to hold documents back to back.

Parameters

dbh – [in] Database handle.
collection – [in] Collection
mode – [in] Mode
start_id – [in] Starting document id
filter – [in] Filter content
filter_size – [in] Filter size
max – [in] Maximum number of documents to return
ids – [out] Ids of the documents returned
bufsize – [in] Size of the document buffer
docs – [out] Buffers in which to receive documents
doc_sizes – [out] Document sizes

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_list_bulk(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t from_id, size_t filter_size, const char *origin, hg_bulk_t data, size_t offset, size_t docs_buf_size, bool packed, size_t count)

Version of yk_doc_list that works on an already formed bulk handle. This bulk handle should expose the filter, then the array of doc sizes, then the array of ids, then the buffer in which to store the documents.

Parameters

dbh – Database handle
collection – Collection
mode – Mode
from_id – Starting id
filter_size – Filter size
origin – Origina address (or NULL if calling process)
data – Bulk handle
offset – Offset in the bulk handle
docs_buf_size – Total buffer size to store documents
packed – Whether documents should be packed
count – Maximum number of documents to return

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_iter(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t start_id, const void *filter, size_t filter_size, size_t max, yk_document_callback_t cb, void *uargs, const yk_doc_iter_options_t *options)

Iterate through up to max documents starting at start_id, calling the callback on each document.

Important: start_id is inclusive, whether YOKAN_MODE_INCLUSIVE is set or not. To exclude it, simply start at start_id+1.

Parameters

dbh – [in] Database handle.
collection – [in] Collection
mode – [in] Mode
start_id – [in] Starting document id
filter – [in] Filter content
filter_size – [in] Filter size
max – [in] Maximum number of documents to return
cb – [in] Callback to call on each document
uargs – [in] Arguments for the callback
options – [in] Options

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_doc_iter_bulk(yk_database_handle_t dbh, const char *collection, int32_t mode, yk_id_t start_id, const void *filter, size_t filter_size, size_t max, yk_document_bulk_callback_t cb, void *uargs, const yk_doc_iter_options_t *options)

Iterate through up to max documents starting at start_id, calling the callback on the bulk handle holding the documents.

Parameters

dbh – [in] Database handle.
collection – [in] Collection
mode – [in] Mode
start_id – [in] Starting document id
filter – [in] Filter content
filter_size – [in] Filter size
max – [in] Maximum number of documents to return
cb – [in] Callback to call on the bulk
uargs – [in] Arguments for the callback
options – [in] Options

Returns

YOKAN_SUCCESS or error code defined in common.h

struct yk_doc_fetch_options

#include <collection.h>

Options to provide to yk_doc_fetch_multi.

Public Members

ABT_pool pool

unsigned batch_size

struct yk_doc_iter_options

#include <collection.h>

Options to pass to yk_doc_iter.

Public Members

unsigned batch_size

ABT_pool pool

common.h

Defines

YOKAN_RETURN_VALUES: Error codes that can be returned by YOKAN functions.

X(__err__, __msg__)

YOKAN_KEY_NOT_FOUND: These two constants are used in returned value sizes to indicate respectively that the buffer was too small to hold the value, and that the key was not found.

YOKAN_SIZE_TOO_SMALL

YOKAN_NO_MORE_KEYS

YOKAN_NO_MORE_DOCS

YOKAN_LAST_VALID_SIZE

YOKAN_MODE_DEFAULT

Modes can be passed to many functions to alter the semantics of the function.

YOKAN_MODE_PACKED: indicate that the data is packed in memory.
YOKAN_MODE_INCLUSIVE: “start” key in “list_keys”/”list_keyvals” is included in results if it is found.
YOKAN_MODE_APPEND: “put” functions will append the provided data to any existing value instead of replacing it.
YOKAN_MODE_CONSUME: “get” and “list” functions will also remove the returned key/value pairs from the database.
YOKAN_MODE_WAIT: “get” will wait for any non-present key to appear in the database instead of returning YOKAN_KEY_NODE_FOUND. Writers need to put their key with YOKAN_MODE_NOTIFY in order to wake up waiters.
YOKAN_MODE_NEW_ONLY: “put” will only add key/value pairs if the key was not already present in the database.
YOKAN_MODE_NO_PREFIX: “list_keys” and “list_keyvals” will remove the prefix from results before sending the keys back.
YOKAN_MODE_IGNORE_KEY: “list_keyvals” will only return values.
YOKAN_MODE_KEEP_LAST: implies YOKAN_MODE_IGNORE_KEYS but “list_keyvals” will still return the last key found. The rest of the keys will be set as empty.
YOKAN_MODE_SUFFIX: consider the “filter” argument of “list_keys” and “list_keyvals” as a suffix instead of a prefix. YOKAN_MODE_NO_PREFIX, if provided, will be re-interpreted accordingly, removing the suffix from the resulting keys.
YOKAN_MODE_LUA_FILTER: interpret the filter as Lua code.
YOKAN_MODE_IGNORE_DOCS: only return IDs of documents matching a filter.
YOKAN_MODE_FILTER_VALUE: filter requires value to be provided.
YOKAN_MODE_LIB_FILTER: filter is the name of a library and a function, separated by a column character.
YOKAN_MODE_NO_RDMA: use a version of the RPC that does not use RDMA for data transfers, when multiple underlying implementations of the RPC exists.
YOKAN_MODE_UPDATE_NEW: allow yk_doc_update to create a document with the specified ID if it does not exist.

Important: not all backends support all modes.

YOKAN_MODE_INCLUSIVE

YOKAN_MODE_APPEND

YOKAN_MODE_CONSUME

YOKAN_MODE_WAIT

YOKAN_MODE_NOTIFY

YOKAN_MODE_NEW_ONLY

YOKAN_MODE_EXIST_ONLY

YOKAN_MODE_NO_PREFIX

YOKAN_MODE_IGNORE_KEYS

YOKAN_MODE_KEEP_LAST

YOKAN_MODE_SUFFIX

YOKAN_MODE_LUA_FILTER

YOKAN_MODE_IGNORE_DOCS

YOKAN_MODE_FILTER_VALUE

YOKAN_MODE_LIB_FILTER

YOKAN_MODE_NO_RDMA

YOKAN_MODE_UPDATE_NEW

Typedefs

typedef enum yk_return_t yk_return_t

typedef uint64_t yk_id_t: Record when working with collections.

Enums

enum yk_return_t

Values:

enumerator YOKAN_RETURN_VALUES

struct yk_migration_options

Public Members

const char *new_root

const char *extra_config

size_t xfer_size

database.h

Defines

YOKAN_DATABASE_HANDLE_NULL

Typedefs

typedef struct yk_database_handle *yk_database_handle_t

typedef yk_return_t (*yk_keyvalue_callback_t)(void*, size_t, const void*, size_t, const void*, size_t)

Type of callback used by the fetch and iter functions.

Param void*: User-provided arguments.
Param size_t: Index of the key/value pair (if fetching multiple).
Param const: void* Key data.
Param size_t: Size of the key.
Param const: void* Value data.
Param size_t: Size of the data.
Return: YK_SUCCESS or other error code.

typedef struct yk_fetch_options yk_fetch_options_t: Options for the yk_fetch_* functions.

typedef struct yk_iter_options yk_iter_options_t

Functions

yk_return_t yk_database_handle_create(yk_client_t client, hg_addr_t addr, uint16_t provider_id, bool check, yk_database_handle_t *handle)

Creates a YOKAN database handle.

Parameters

client – [in] YOKAN client responsible for the database handle
addr – [in] Mercury address of the provider
provider_id – [in] id of the provider
check – [in] Checks if the provider is valid
handle – [out] database handle

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_database_handle_get_info(yk_database_handle_t handle, yk_client_t *client, hg_addr_t *addr, uint16_t *provider_id)

Retrieve the internal information from a database handle. Any NULL pointer will be ignored. The hg_addr_t addr field, if set, needs to be free by the caller using margo_addr_free.

Parameters

handle – [in] YOKAN database handle
client – [out] Client used to create the handle
addr – [out] Address of the handle
provider_id – [out] Provider id of the handle

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_database_handle_ref_incr(yk_database_handle_t handle)

Increments the reference counter of a database handle.

Parameters: handle – database handle
Returns: YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_database_handle_release(yk_database_handle_t handle)

Releases the database handle. This will decrement the reference counter, and free the database handle if the reference counter reaches 0.

Parameters: handle – [in] database handle to release.
Returns: YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_count(yk_database_handle_t dbh, int32_t mode, size_t *count)

Get the number of key/val pairs stored in the database.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [out] Number of pairs stored.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_put(yk_database_handle_t dbh, int32_t mode, const void *key, size_t ksize, const void *value, size_t vsize)

Put a single key/value pair into the database.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
key – [in] Key.
ksize – [in] Size of the key.
value – [in] Value.
vsize – [in] Size of the value.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_put_multi(yk_database_handle_t dbh, int32_t mode, size_t count, const void *const *keys, const size_t *ksizes, const void *const *values, const size_t *vsizes)

Put multiple key/value pairs into the database. The keys and values are provided by arrays of points, and may not be contiguous in memory.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/value pairs.
keys – [in] Array of pointers to keys.
ksizes – [in] Array of key sizes.
values – [in] Array of pointers to values.
vsizes – [in] Array of value sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_put_packed(yk_database_handle_t dbh, int32_t mode, size_t count, const void *keys, const size_t *ksizes, const void *values, const size_t *vsizes)

Put multiple key/value pairs into the database. The keys and values are provided via contiguous memory segments.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/value pairs.
keys – [in] Buffer containing keys.
ksizes – [in] Array of key sizes.
values – [in] Buffer containing values.
vsizes – [in] Array of value sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_put_bulk(yk_database_handle_t dbh, int32_t mode, size_t count, const char *origin, hg_bulk_t data, size_t offset, size_t size)

Low-level put operation based on a bulk handle. This function will take the data in [offset, offset+size[ from the bulk handle and interpret it as follows:

The first count * sizeof(size_t) bytes store the key sizes.
The next count * sizeof(size_t) bytes store the value sizes.
The next N bytes store keys back to back, where N = sum of key sizes
The last M bytes store values back to bake, where M = sum of value sizes Origin represents the address of the process that created the bulk handle. If NULL, the bulk handle is considered to have been created by the calling process.

This function is useful in situation where a process received a bulk handle from another process and wants to forward it to an YOKAN provider.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/values in the bulk data.
origin – [in] Address of the process that created the bulk handle.
data – [in] Bulk handle containing the data.
offset – [in] Offset at which the payload starts in the bulk handle.
size – [in] Size of the payload in the bulk handle.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_exists(yk_database_handle_t dbh, int32_t mode, const void *key, size_t ksize, uint8_t *exists)

Check if the key exists in the database. exists is set to 1 if the key exists, 0 otherwise.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
key – [in] Key.
ksize – [in] Size of the key.
exists – [out] Whether the key exists.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_exists_multi(yk_database_handle_t dbh, int32_t mode, size_t count, const void *const *keys, const size_t *ksizes, uint8_t *flags)

Check if the list of keys exist in the database. The flags argument is a pointer to an arrat of size ceil(count/8). Each bit (not byte!) in this array indicates the presence (1) or absence (0) of a corresponding key. The yk_unpack_exists_flag function can be used to return proper booleans from this array.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of keys to check.
keys – [in] Array of pointers to keys.
ksizes – [in] Array of key sizes.
flags – [out] Bitfield indicating whether each key exists.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_exists_packed(yk_database_handle_t dbh, int32_t mode, size_t count, const void *keys, const size_t *ksizes, uint8_t *flags)

Same as yk_exists_multi but keys are packed contiguously in memory.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of keys to check.
keys – [in] Packed keys.
ksizes – [in] Array of key sizes.
flags – [out] Bitfield indicating whether each key exists.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_exists_bulk(yk_database_handle_t dbh, int32_t mode, size_t count, const char *origin, hg_bulk_t data, size_t offset, size_t size)

Low-level exists operation based on a bulk handle. This function will take the data in [offset, offset+size[ from the bulk handle and interpret it as follows:

The first count * sizeof(size_t) bytes store the key sizes.
The next N bytes store keys back to back, where N = sum of key sizes
The last M bytes will be used to store the resulting bitfield where M = ceil(count/8) Origin represents the address of the process that created the bulk handle. If NULL, the bulk handle is considered to have been created by the calling process.

This function is useful in situation where a process received a bulk handle from another process and wants to forward it to an YOKAN provider.

Note: the bulk handle must have been created with HG_BULK_READWRITE.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/values in the bulk data.
origin – [in] Address of the process that created the bulk handle.
data – [in] Bulk handle containing the data.
offset – [in] Offset at which the payload starts in the bulk handle.
size – [in] Size of the payload in the bulk handle.

Returns

YOKAN_SUCCESS or corresponding error code.

static inline bool yk_unpack_exists_flag(const uint8_t *flags, size_t i)

Interpret the bitfield returned by the yk_exists_multi, yk_exists_packed, and yk_exists_bulk operation, taking the flags array (as passed to these operations) and an index i, and returning whether key i exists.

Parameters

flags – bitfield.
i – index of the key.

Returns

whether key at index i exists.

yk_return_t yk_length(yk_database_handle_t dbh, int32_t mode, const void *key, size_t ksize, size_t *vsize)

Get the length of the value associated with a key.

Parameters

dbh – [in] Database Handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
key – [in] Key.
ksize – [in] Size of the key.
vsize – [out] Size of the value.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_length_multi(yk_database_handle_t dbh, int32_t mode, size_t count, const void *const *keys, const size_t *ksizes, size_t *vsizes)

Get the size of the values associates with a list of keys. The vsizes pointer should point to a preallocated array of count elements.

Note that contrary to yk_length, which will return YOKAN_ERR_KEY_NOT_FOUND if the key is not found, the yk_length_multi function will return YOKAN_SUCCESS (even when none of the keys are found) and size of keys not found will be set to YOKAN_KEY_NOT_FOUND.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of keys.
keys – [in] Array of pointers to keys.
ksizes – [in] Array of key sizes.
vsizes – [out] Resulting array of value sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_length_packed(yk_database_handle_t dbh, int32_t mode, size_t count, const void *keys, const size_t *ksizes, size_t *vsizes)

Same as yk_length_multi but the keys are packed contiguously in memory.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of keys.
keys – [in] Packed keys.
ksizes – [in] Array of key sizes.
vsizes – [out] Resulting array of value sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_length_bulk(yk_database_handle_t dbh, int32_t mode, size_t count, const char *origin, hg_bulk_t data, size_t offset, size_t size)

Low-level length operation based on a bulk handle. This function will take the data in [offset, offset+size[ from the bulk handle and interpret it as follows:

The first count * sizeof(size_t) bytes store the key sizes.
The next N bytes store keys back to back, where N = sum of key sizes
The last count * sizeof(size_t) bytes will be used to store the resulting value sizes. Origin represents the address of the process that created the bulk handle. If NULL, the bulk handle is considered to have been created by the calling process.

This function is useful in situation where a process received a bulk handle from another process and wants to forward it to an YOKAN provider.

Note: the bulk handle must have been created with HG_BULK_READWRITE.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/values in the bulk data.
origin – [in] Address of the process that created the bulk handle.
data – [in] Bulk handle containing the data.
offset – [in] Offset at which the payload starts in the bulk handle.
size – [in] Size of the payload in the bulk handle.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_get(yk_database_handle_t dbh, int32_t mode, const void *key, size_t ksize, void *value, size_t *vsize)

Get the value associated with a key. The vsize argument provides the initial length of the value buffer, and is set to the actual value size upon success of this function. If the key if not found, the function will return YOKAN_ERR_KEY_NOT_FOUND. If the key is found but the value buffer is too small to hold the value, the function will return YOKAN_ERR_BUFFER_SIZE. In these cases the vsize parameter will be set to YOKAN_KEY_NOT_FOUND and YOKAN_SIZE_TOO_SMALL respectively.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
key – [in] Key.
ksize – [in] Size of the key.
value – [out] Value buffer.
vsize – [inout] Size of the buffer, then set to size of the value.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_get_multi(yk_database_handle_t dbh, int32_t mode, size_t count, const void *const *keys, const size_t *ksizes, void *const *values, size_t *vsizes)

Get the values associated with a set of keys. For any key that is not found, the corresponding value size will be set to YOKAN_KEY_NOT_FOUND. For any key that is found but for which the provided value buffer is too small for the value, the corresponding value size will be set to YOKAN_SIZE_TOO_SMALL.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/value pairs.
keys – [in] Array of keys.
ksizes – [in] Arrat of key sizes.
values – [out] Array of value buffers.
vsizes – [inout] Array of buffer sizes, set to value sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_get_packed(yk_database_handle_t dbh, int32_t mode, size_t count, const void *keys, const size_t *ksizes, size_t vbufsize, void *values, size_t *vsizes)

Get the values associated with a set of keys. The keys are packed contiguously in memory. This function will also pack values contiguously in the provided memory.

For any key that is not found, the corresponding value size will be set to YOKAN_KEY_NOT_FOUND. Once the function reaches a key whose associated value is too big to fit in the buffer, the rest of the value sizes will be set to YOKAN_SIZE_TOO_SMALL.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/value pairs.
keys – [in] Packed keys.
ksizes – [in] Arrat of key sizes.
vbufsize – [in] Total memory available in values buffer.
values – [out] Buffer to hold packed values.
vsizes – [out] Value sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_get_bulk(yk_database_handle_t dbh, int32_t mode, size_t count, const char *origin, hg_bulk_t data, size_t offset, size_t size, bool packed)

Low-level get operation based on a bulk handle. This function will take the data in [offset, offset+size[ from the bulk handle and interpret it as follows:

The first count * sizeof(size_t) bytes store the key sizes.
The next count * sizeof(size_t) bytes store the value sizes.
The next N bytes store keys back to back, where N = sum of key sizes
The last M bytes store values back to bake, where M = sum of value sizes Origin represents the address of the process that created the bulk handle. If NULL, the bulk handle is considered to have been created by the calling process.

This function is useful in situation where a process received a bulk handle from another process and wants to forward it to an YOKAN provider.

Note: the “packed” argument is important. It specifies whether the process that created the bulk handle did so by exposing a single contiguous buffer in which packed values are meant to be stored (in which case the value sizes do not matter as an input), or if individual buffers were exposed to hold each value (in which case the value sizes do matter as an input).

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/values in the bulk data.
origin – [in] Address of the process that created the bulk handle.
data – [in] Bulk handle containing the data.
offset – [in] Offset at which the payload starts in the bulk handle.
size – [in] Size of the payload in the bulk handle.
packed – [in] Whether values are packed on the client end.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_fetch(yk_database_handle_t dbh, int32_t mode, const void *key, size_t ksize, yk_keyvalue_callback_t cb, void *uargs)

This function performs a GET but instead of providing a buffer in which to receive the value, the caller provides a function to call on the fetched key/value pair. This function is useful when the size of the value is unknown, but yk_get should be preferred if the size is known.

Important: the key/value data passed to the callback are guaranteed to be valid only until the callback returns. Hence if the callback

Important: for this function to work, the calling process must have a margo instance running in server mode.

Parameters

dbh – Database handle.
mode – 0 or bitwise “or” of YOKAN_MODE_* flags.
key – Key data.
ksize – Size of the key.
cb – Callback to invoke on the key/value pair.
uargs – Argument for the callback.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_fetch_packed(yk_database_handle_t dbh, int32_t mode, size_t count, const void *keys, const size_t *ksizes, yk_keyvalue_callback_t cb, void *uargs, const yk_fetch_options_t *options)

Packed version of yk_fetch meant to fetch multiple values at once from a pack of keys.

The options argument, if provided, will indicate how the processing is done.

Parameters

dbh – Database handle.
mode – 0 or bitwise “or” of YOKAN_MODE_* flags.
count –
keys – Packed keys data.
ksizes – Size of the keys.
cb – Callback to invoke on the key/value pair.
uargs – Argument for the callback.
options – Batching and parallelism options.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_fetch_multi(yk_database_handle_t dbh, int32_t mode, size_t count, const void *const *keys, const size_t *ksizes, yk_keyvalue_callback_t cb, void *uargs, const yk_fetch_options_t *options)

Multi version of yk_fetch meant to fetch multiple values at once from an array of keys.

The options argument, if provided, will indicate how the processing is done.

Parameters

dbh – Database handle.
mode – 0 or bitwise “or” of YOKAN_MODE_* flags.
count –
keys – keys data.
ksizes – Size of the keys.
cb – Callback to invoke on the key/value pair.
uargs – Argument for the callback.
options – Batching and parallelism options.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_fetch_bulk(yk_database_handle_t dbh, int32_t mode, size_t count, const char *origin, hg_bulk_t data, size_t offset, size_t size, yk_keyvalue_callback_t cb, void *uargs, const yk_fetch_options_t *options)

Bulk version of yk_fetch meant to fetch multiple values at once from a bulk representing the data (array of size_t followed by the actual keys).

The options argument, if provided, will indicate how the processing is done.

Parameters

dbh – Database handle.
mode – 0 or bitwise “or” of YOKAN_MODE_* flags.
count –
keys – keys data.
ksizes – Size of the keys.
cb – Callback to invoke on the key/value pair.
uargs – Argument for the callback.
options – Batching and parallelism options.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_erase(yk_database_handle_t dbh, int32_t mode, const void *key, size_t ksize)

Erase a key/value pair associated with the given key. Note that this function will not return an error if the key does not exist.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
key – [in] Key to erase.
ksize – [in] Size of the key.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_erase_multi(yk_database_handle_t dbh, int32_t mode, size_t count, const void *const *keys, const size_t *ksizes)

Erase multiple key/value pairs.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/value pairs.
keys – [in] Array of keys.
ksizes – [in] Array of key sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_erase_packed(yk_database_handle_t dbh, int32_t mode, size_t count, const void *keys, const size_t *ksizes)

Erase multiple key/value pairs. Contrary to yk_erase_multi, the keys are packed into a single contiguous buffer.

Parameters

dbh – Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – Number of key/value pairs.
keys – Packed keys.
ksizes – Size of the keys.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_erase_bulk(yk_database_handle_t dbh, int32_t mode, size_t count, const char *origin, hg_bulk_t data, size_t offset, size_t size)

Low-level erase operation based on a bulk handle. This function will take the data in [offset, offset+size[ from the bulk handle and interpret it as follows:

The first count * sizeof(size_t) bytes store the key sizes.
The next N bytes store keys back to back, where N = sum of key sizes Origin represents the address of the process that created the bulk handle. If NULL, the bulk handle is considered to have been created by the calling process.

This function is useful in situation where a process received a bulk handle from another process and wants to forward it to an YOKAN provider.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
count – [in] Number of key/values in the bulk data.
origin – [in] Address of the process that created the bulk handle.
data – [in] Bulk handle containing the data.
offset – [in] Offset at which the payload starts in the bulk handle.
size – [in] Size of the payload in the bulk handle.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_list_keys(yk_database_handle_t dbh, int32_t mode, const void *from_key, size_t from_ksize, const void *filter, size_t filter_size, size_t count, void *const *keys, size_t *ksizes)

Lists up to count keys from from_key (included if inclusive is set to true), filtering keys if a filter is provided.

Unless a specific mode is used to change it, the filter is considered as a prefix that the keys must start with.

If a key size is too small to hold the key, the size will be set to YOKAN_SIZE_TOO_SMALL.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
from_key – [in] Starting key.
from_ksize – [in] Starting key size.
filter – [in] Key filter.
filter_size – [in] Filter size.
count – [in] Max keys to read (in) / number actually read (out).
keys – [out] Array of buffers to hold keys.
ksizes – [inout] Array of key sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_list_keys_packed(yk_database_handle_t dbh, int32_t mode, const void *from_key, size_t from_ksize, const void *filter, size_t filter_size, size_t count, void *keys, size_t keys_buf_size, size_t *ksizes)

Same as yk_list_keys but using a contiguous buffer to hold keys.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
from_key – [in] Starting key.
from_ksize – [in] Starting key size.
filter – [in] Key filter.
filter_size – [in] Filter size.
count – [in] Max keys to read.
keys – [out] Buffer to hold keys.
keys_buf_size – [in] Size of the buffer to hold keys.
ksizes – [out] Array of key sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_list_keys_bulk(yk_database_handle_t dbh, int32_t mode, size_t from_ksize, size_t filter_size, const char *origin, hg_bulk_t data, size_t offset, size_t keys_buf_size, bool packed, size_t count)

Low-level list_keys operation using a bulk handle. This function will take the data in [offset, offset+size[ from the bulk handle and interpret it as follows:

The first from_ksize bytes represent the start key.
The next filter_size byres represent the filter.
The next count * sizeof(size_t) bytes represent the key sizes.
The next N bytes store keys back to back, where N = sum of key sizes Origin represents the address of the process that created the bulk handle. If NULL, the bulk handle is considered to have been created by the calling process.

This function is useful in situation where a process received a bulk handle from another process and wants to forward it to an YOKAN provider.

Note: the bulk handle must have been created with HG_BULK_READWRITE.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
from_ksize – [in] Starting key size.
filter_size – [in] Filter size.
origin – [in] Origin address.
data – [in] Bulk handle containing the data.
offset – [in] Offset at which the payload starts in the bulk handle.
keys_buf_size – [in] Total size allocated for keys.
packed – [in] Whether keys are packed on the client.
count – [in] Max keys to read.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_list_keyvals(yk_database_handle_t dbh, int32_t mode, const void *from_key, size_t from_ksize, const void *filter, size_t filter_size, size_t count, void *const *keys, size_t *ksizes, void *const *values, size_t *vsizes)

Lists up to count key/value pairs from from_key (included if inclusive is set to true), filtering keys if a filter is provided.

Unless a specific mode is used to change it, the filter is considered as a prefix that the keys must start with.

If a key size is too small to hold the key, the size will be set to YOKAN_SIZE_TOO_SMALL. If a value size is too small to hold the value, the size will be set to YOKAN_SIZE_TOO_SMALL.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
from_key – [in] Starting key.
from_ksize – [in] Starting key size.
filter – [in] Key filter.
filter_size – [in] Filter size.
count – [in] Max keys to read.
keys – [out] Array of buffers to hold keys.
ksizes – [inout] Array of key sizes.
values – [out] Array of buffers to hold values.
vsizes – [inout] Array of value sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_list_keyvals_packed(yk_database_handle_t dbh, int32_t mode, const void *from_key, size_t from_ksize, const void *filter, size_t filter_size, size_t count, void *keys, size_t keys_buf_size, size_t *ksizes, void *values, size_t vals_buf_size, size_t *vsizes)

Same as yk_list_keyvals but using contiguous buffers to hold keys and values.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
from_key – [in] Starting key.
from_ksize – [in] Starting key size.
filter – [in] Key filter.
filter_size – [in] Filter size.
count – [in] Max keys to read.
keys – [out] Buffer to hold keys.
keys_buf_size – [in] Size of the buffer to hold keys.
ksizes – [out] Array of key sizes.
values – [out] Buffer to hold values.
vals_buf_size – [in] Size of the buffer to hold values.
vsizes – [out] Array of value sizes.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_list_keyvals_bulk(yk_database_handle_t dbh, int32_t mode, size_t from_ksize, size_t filter_size, const char *origin, hg_bulk_t data, size_t offset, size_t key_buf_size, size_t val_buf_size, bool packed, size_t count)

Low-level list_keyvals operation using a bulk handle. This function will take the data in [offset, offset+size[ from the bulk handle and interpret it as follows:

The first from_ksize bytes represent the start key.
The next filter_size byres represent the filter.
The next count * sizeof(size_t) bytes represent the key sizes.
The next count * sizeof(size_t) bytes represent the value sizes.
The next key_buf_size bytes will store keys back to back
The next val_buf_size bytes will store values back to back Origin represents the address of the process that created the bulk handle. If NULL, the bulk handle is considered to have been created by the calling process.

This function is useful in situation where a process received a bulk handle from another process and wants to forward it to an YOKAN provider.

Note: the bulk handle must have been created with HG_BULK_READWRITE.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
from_ksize – [in] Starting key size.
filter_size – [in] Filter size.
origin – [in] Origin address.
data – [in] Bulk handle containing the data.
offset – [in] Offset at which the payload starts in the bulk handle.
key_buf_size – [in] Size of the buffer allocated for keys.
val_buf_size – [in] Size of the buffer allocated for values.
packed – [in] Whether the data is packed on the client side.
count – [in] Max keys to read.

Returns

YOKAN_SUCCESS or corresponding error code.

yk_return_t yk_iter(yk_database_handle_t dbh, int32_t mode, const void *from_key, size_t from_ksize, const void *filter, size_t filter_size, size_t count, yk_keyvalue_callback_t cb, void *uargs, const yk_iter_options_t *options)

Iterate up to max key/value pairs from from_key (included if inclusive is set in the mode), filtering keys if a filter is provided.

Unless a specific mode is used to change it, the filter is considered as a prefix that the keys must start with.

If count is set to 0, this function will iterate until the end. If ignore_values is set to true in the options, the callback will be invoked with NULL values and value size of 0.

Parameters

dbh – [in] Database handle.
mode – [in] 0 or bitwise “or” of YOKAN_MODE_* flags.
from_key – [in] Starting key.
from_ksize – [in] Starting key size.
filter – [in] Key filter.
filter_size – [in] Filter size.
count – [in] Max keys to read, 0 for all.
cb – [in] Callback to call in each key.
uargs – [in] Callback user-argument.
options – [in] Options.

Returns

YOKAN_SUCCESS or corresponding error code.

struct yk_fetch_options

#include <database.h>

Options for the yk_fetch_* functions.

Public Members

ABT_pool pool

unsigned batch_size

struct yk_iter_options

Public Members

unsigned batch_size

ABT_pool pool

bool ignore_values

server.h

Defines

YOKAN_ABT_POOL_DEFAULT

YOKAN_PROVIDER_NULL

YOKAN_PROVIDER_IGNORE

YOKAN_PROVIDER_ARGS_INIT

Typedefs

typedef struct yk_provider *yk_provider_t

typedef struct remi_client *remi_client_t

typedef struct remi_provider *remi_provider_t

Functions

yk_return_t yk_provider_register(margo_instance_id mid, uint16_t provider_id, const char *config, const struct yk_provider_args *args, yk_provider_t *provider)

Creates a new YOKAN provider. If YOKAN_PROVIDER_IGNORE is passed as last argument, the provider will be automatically destroyed when calling margo_finalize.

Parameters

mid – [in] Margo instance
provider_id – [in] provider id
config – [in] Configuration
args – [in] argument structure
provider – [out] provider

Returns

YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_provider_destroy(yk_provider_t provider)

Destroys the YOKAN provider and deregisters its RPC.

Parameters: provider – [in] YOKAN provider
Returns: YOKAN_SUCCESS or error code defined in common.h

yk_return_t yk_provider_migrate_database(yk_provider_t provider, const char *dest_addr, uint16_t dest_provider_id, const struct yk_migration_options *options)

Migrates the database from the given provider to the target provider.

Parameters

provider –
dest_addr –
dest_provider_id –
options –

Returns

YOKAN_SUCCESS or error code defined in common.h

char *yk_provider_get_config(yk_provider_t provider): Returns the internal configuration of the YOKAN provider. The returned string must be free-ed by the caller.

struct yk_provider_args

Public Members

ABT_pool pool

yk_bulk_cache_t cache

remi_client_t client

remi_provider_t provider

struct yk_provider_args remi