Create a key/value store instance
int ark_create(file, ark, flags)
char * file;
ARK ** handle;
uint64_t flags;
The ark_create API will create a key/value store instance on the host system.
The path parameter can be used to specify the special file (e.g. /dev/sdx) representative of the physical LUN created on the flash store. If the path parameter is not a special file, the API will assume it is a file to be used for the key/value store. If the file does not exist, it will be created. If path is NULL, memory will be used for the key/value store.
The parameter, flags, will indicate the properties of the KV store. In the case of specifying a special file for the physical LUN, the user can specify whether the KV store is use the physical LUN as is or to create the KV store in a virtual LUN. By default, the entire physical LUN will be used for the KV store. If a virtual LUN is desired, the ARK_KV_VIRTUAL_LUN bit must be set in the flags parameter.
In this revision, a KV store configured to use the entire physical LUN can be persisted. Persistence of a KV store allows the user to shut down an ARK instance and at a later time open the same physical LUN and load the previous ARK instance to the same state as it was when it closed. To configure an ARK instance to be persisted at shut down (ark_delete), set the ARK_KV_PERSIST_STORE bit in the flags parameter. By default, an ARK instance is not configured to be persisted. To load the persisted ARK instance resident on the physical LUN, set the ARK_KV_PERSIST_LOAD bit in the flags parameter. By default, the persisted store, if present, will not be loaded and will potentially be overwritten by any new persisted data.
In this revision, only physical LUN KV stores can be persisted.
Upon successful completion, the handle parameter will represent the newly created key/value store instance to be used for future API calls.
| Parameter | Description |
| path | Allows the user to specify a specific CAPI adapter, a file, or memory for the key/value store. |
| ark | Handle representing the key/value store |
| flags | Collection of bit flags determining the properties of the KV store. |
|
| | - ARK_KV_VIRTUAL_LUN: KV store will use a virtual LUN created from the physical LUN represented by the special file, file.
| |
| | - ARK_KV_PERSIST_STORE: Configure the ARK instance to be persisted upon closing (ark_delete)
|
| | - ARK_KV_PERSIST_LOAD: If persistence data is present on the physical LUN, then load the configuration stored. |
Upon successful completion, the ark_create API will return 0, and the handle parameter will point to the newly created key/value store instance. If unsuccessful, the ark_create API will return a non-zero error code:
| Error | Reason |
| EINVAL | Invalid value for one of the parameters |
| ENOSPC | Not enough memory or flash storage |
| ENOTREADY | System not ready for key/value store supported configuration |
Delete a key/value store instance
int ark_delete(ark)
ARK * ark;
The ark_delete API will delete a key/value store instance, specified by the ark parameter, on the host system. Upon successfully completion all associated in memory and storage resources will be released at this time.
If the ARK instance is configured to be persisted, it is at this time the configuration will be persisted so that it may be loaded at a future time.
| Parameter | Description |
| ark | Handle representing the key/value store instance. |
Upon successful completion, the ark_delete API will clean and remove all resources associated with the key/value store instance and return 0. If unsuccessful, the ark_delete API will return a non-zero error code:
| Error | Reason |
| EINVAL | key/value store handle is not valid |
Write a key/value pair
int ark_set(ark, klen, key, vlen, val, res)
int ark_set_async_cb(ark, klen, key, vlen, val, callback, dt)
ARK * ark;
uint64_t klen;
void * key;
uint64_t vlen;
void * val;
void *(*callback)(int errcode, uint64_t dt, uint64_t res);
uint64_t dt;
The ark_set API will store the key, key, and value, val, into the store for the key/value store instance represented by the ark parameter The API, ark_set_async_cb, will behave in the same manner, but in an asynchronous fashion, where the API immediately returns to the caller and the actual operation is scheduled to run. After the operation is executed, the callback function will be called to notify the caller of completion.
If the key is present, the stored value will be replaced with the val value.
Upon successful completion, the key/value pair will be present in the store and the number of bytes written will be returned to the caller through the res parameter.
| Parameter | Description |
| ark | Handle representing the key/value store instance connection |
| klen | Length of the key in bytes. |
| key | Key |
| vlen | Length of the value in bytes. |
| val | Value |
| res | Upon success, number of bytes written to the store. |
| callback | Function to call upon completion of the I/O operation. |
| dt | 64bit value to tag an asynchronous API call. |
Upon successful completion, the ark_set and ark_set_async_cbAPI will write the key/value in the store associated with the key/value store instance and return the number of bytes written. The return of ark_set will indicate the status of the operation. The ark_set_async_cb API return will indicate whether the asynchronous operation was accepted or rejected. The true status will be stored in the errcode parameter when the callback function is executed. If unsuccessful, the ark_set and ark_set_async_cb API will return a non-zero error code:
| Error | Reason |
| EINVAL | Invalid parameter |
| ENOSPC | Not enough space left in key/value store store |
Retrieve a value for a given key
int ark_get(ark, klen, key, vbuflen, vbuf, voff, res)
int ark_get_async_cb(ark, klen, key, vbuflen, vbuf, voff, callback, dt)
ARK * ark;
uint64_t klen;
void * key;
uint64_t vbuflen;
void * vbuf;
uint64_t voff;
void *(*callback)(int errcode, uint64_t dt, uint64_t res);
uint64_t dt;
The ark_get and ark_get_async_cb API will query the key/value store store associated with the ark paramter for the given key, key. If found, the key's value will be returned in the vbuf parameter with at most vbuflen bytes written starting at the offset, voff, in the key's value. The API, ark_get_async_cb, will behave in the same manner, but in an asynchronous fashion, where the API immediately returns to the caller and the actual operation is scheduled to run. After the operation is executed, the callback function will be called to notify the caller of completion.
If successful, the length of the key's value is stored in the res parameter of the callback function.
| Parameter | Description |
| ark | Handle representing the key/value store instance connection. |
| klen | Length of the key in bytes. |
| key | Key |
| vbuflen | Length of the buffer, vbuf |
| vbuf | Buffer to store the key's value |
| voff | Offset into the key to start reading. |
| res | If successful, will store the size of the key in bytes |
| callback | Function to call upon completion of the I/O operation. |
| dt | 64bit value to tag an asynchronous API call. |
Upon successful completion, the ark_get and ark_get_async_cb API will return 0. The return of ark_get will indicate the status of the operation. The ark_get_async_cb API return will indicate whether the asynchronous operation was accepted or rejected. The true status of the asynchronous API will be stored in the errcode parameter of the callback function. If unsuccessful, the ark_get and ark_set_async_cb API will return a non-zero error code:
| Error | Reason |
| EINVAL | Invalid parameter |
| ENOENT | Key not found |
| ENOSPC | Buffer not big enough to hold value |
Delete the value associated with a given key
int ark_del(ark, klen, key, res)
int ark_del_async_cb(ark, klen, key, callback, dt)
ARK * ark;
uint64_t klen;
void * key;
void *(*callback)(int errcode, uint64_t dt, uint64_t res);
uint64_t dt;
The ark_del and ark_del_async_cb API will query the key/value store store associated with the handle paramter for the given key, key, and if found, will delete the value. The API, ark_del_async_cb, will behave in the same manner, but in an asynchronous fashion, where the API immediately returns to the caller and the actual operation is scheduled to run. After the operation is executed, the callback function will be called to notify the caller of completion.
If successful, the length of the key's value is returned to the caller in the res parameter of the callback function.
| Parameter | Description |
| ark | Handle representing the key/value store instance connection. |
| klen | Length of the key in bytes. |
| key | Key |
| res | If successful, will store the size of the key in bytes |
| callback | Function to call upon completion of the I/O operation. |
| dt | 64bit value to tag an asynchronous API call. |
Upon successful completion, the ark_del and ark_del_async_cb API will return 0. The return of ark_del will indicate the status of the operation. The ark_del_async_cb API return will indicate whether the asynchronous operation was accepted or rejected. The true status will be returned in the errcode parameter when the callback function is executed. If unsuccessful, the ark_del and ark_del_async_cb API will return a non-zero error code:
| Error | Reason |
| EINVAL | Invalid parameter |
| ENOENT | Key not found |
Query the key/value store store to see if a given key is present
int ark_exists(ark, klen, key, res)
int ark_exists_async_cb(ark, klen, key, callback, dt)
ARK * ark;
uint64_t klen;
void * key;
void *(*callback)(int errcode, uint64_t dt, uint64_t res);
uint64_t dt;
The ark_exists and ark_exists_async_cb API will query the key/value store store associated with the ark or arc paramter for the given key, key, and if found, return the size of the value in bytes in the res parameter. The key and it's value will not be altered. The API, ark_exists_async_cb, will behave in the same manner, but in an asynchronous fashion, where the API immediately returns to the caller and the actual operation is scheduled to run. After the operation is executed, the callback function will be called to notify the caller of completion.
| Parameter | Description |
| ark | Handle representing the key/value store instance connection. |
| klen | Length of the key in bytes. |
| key | Key |
| res | If successful, will store the size of the key in bytes |
| callback | Function to call upon completion of the I/O operation. |
| dt | 64bit value to tag an asynchronous API call. |
Upon successful completion, the ark_exists and ark_exists_async_cb API will return 0. The return of ark_exists will indicate the status of the operation. The ark_exists_async_cb API return will indicate whether the asynchronous operation was accepted or rejected. The true status will be returned in the errcode parameter when the callback function is executed. If unsuccessful, the ark_exists and ark_exists_async_cb API will return a non-zero error code:
| Error | Reason |
| EINVAL | Invalid parameter |
| ENOENT | Key not found |
Return the first key and handle to iterate through store.
ARI * ark_first(ark, kbuflen, klen, kbuf)
ARK * ark;
uint64_t kbuflen
int64_t klen;
void * kbuf;
The ark_first API will return the first key found in the store in the buffer, kbuf, and the size of the key in klen, as long as the size is less than the size of the kbuf, kbuflen.
If successful, an iterator handle will be returned to the caller to be used to retrieve the next key in the store by calling the ark_next API.
| Parameter | Description |
| ark | Handle representing the key/value store instance connection. |
| kbuflen | Length of the kbuf parameter. |
| klen | Size of the key returned in kbuf |
| kbuf | Buffer to hold the key |
Upon successful completion, the ark_first API will return a handle to be used to iterate through the store on subsequent calls using the ark_next API. If unsuccessful, the ark_first API will return NULL with errno set to one of the following:
| Error | Reason |
| EINVAL | Invalid parameter |
| ENOSPC | kbuf is too small to hold key |
Return the next key in the store.
ARI * ark_next(iter, kbuflen, klen, kbuf)
ARI * iter;
uint64_t kbuflen
int64_t klen;
void * kbuf;
The ark_next API will return the next key found in the store based on the iterator handle, iter, in the buffer, kbuf, and the size of the key in klen, as long as the size is less than the size of the kbuf, kbuflen.
If successful, a handle will be returned to the caller to be used to retrieve the next key in the store by calling the ark_next API. If the end of the store is reached, a NULL value is returned and errno set to ENOENT.
Because of the dynamic nature of the store, some recently written keys may not be returned.
| Parameter | Description |
| iter | Iterator handle where to begin search in store |
| kbuflen | Length of the kbuf parameter. |
| klen | Size of the key returned in kbuf |
| kbuf | Buffer to hold the key |
Upon successful completion, the ark_next API will return a handle to be used to iterate through the store on subsequent calls using the ark_next API. If unsuccessful, the ark_next API will return NULL with errno set to one of the following:
| Error | Reason |
| EINVAL | Invalid parameter |
| ENOSPC | kbuf is too small to hold key |
| ENOENT | End of the store has been reached. |
Return the number of bytes allocated in the store.
int ark_allocated(ark, size)
ARK * ark;
uint64_t *size;
The ark_allocated API will return the number of bytes allocated in the store in the size parameter.
| Parameter | Description |
| ark | Handle representing the key/value store instance. |
| size | Will hold the size of the store in bytes |
Upon successful completion, the ark_allocated API will return 0. If unsuccessful, the ark_allocated API will return one of the following error codes.
| Error | Reason |
| EINVAL | Invalid parameter |
Return the number of bytes in use in the store.
int ark_inuse(ark, size)
ARK *ark;
uint64_t *size;
The ark_inuse API will return the number of bytes in use in the store in the size parameter.
| Parameter | Description |
| ark | Handle representing the key/value store instance. |
| size | Will hold the size of number of blocks in use. Size will be in bytes. |
Upon successful completion, the ark_inuse API will return 0. If unsuccessful, the ark_inuse API will return one of the following error codes:
| Error | Reason |
| EINVAL | Invalid parameter |
Return the actual number of bytes in use in the store.
int ark_actual(ark, size)
ARK *ark;
uint64_t *size;
The ark_actual API will return the actual number of bytes in use in the store in the size parameter. This differs from the ark_inuse API as this takes into account the actual sizes of the individual keys and their values instead of generic allocations based on blocks to store these values.
| Parameter | Description |
| ark | Handle representing the key/value store instance. |
| size | Will hold the actual number of bytes in use in the store. |
Upon successful completion, the ark_actual API will return the 0. If unsuccessful, the ark_actual API will return one of the following error codes:
| Error | Reason |
| EINVAL | Invalid parameter |
Return additional error information on a failure.
int ark_error(ark)
ARK * ark;
char * ark_errorstring(ark)
ARK * ark;
The ark_error API will return a more descriptive error code for the last error encountered on a key/value store API.
The ark_errorstring API will return a human readable error string for the last error encountered on a key/value store API.
| Parameter | Description |
| ark | Handle representing the key/value store instance. |
Upon successful completion, ark_error will return a non-zero value and ark_errorstring will return a non-NULL value. If an error is encountered, ark_error will return a negative error code and ark_errorstring will return NULL with errno set to one of the following:
| Error | Reason |
| EINVAL | Invalid parameter |
Fork a key/value store for archiving purposes.
int ark_fork(ark)
int ark_fork_done(ark)
ARK * handle;
The ark_fork and ark_fork_done API's are to be called by the parent key/value store process to prepare the key/value store to be forked, fork the child process, and to perform any cleanup once it has been detected the child process has exited.
The ark_fork API will fork a child process and upon return, will return the process ID of the child in the parent process, and 0 in the child process. Once the parent detects the child has exited, a call to ark_fork_done will be needed to clean up any state from the ark_fork call.
Note, the ark_fork API will fail if there are any outstanding asynchronous commands.
| Parameter | Description |
| ark | Handle representing the key/value store instance. |
Upon successful completion, ark_fork and ark_fork_done will return 0, otherwise one of the following errors:
| Error | Reason |
| EINVAL | Invalid parameter |
| EBUSY | Outstanding asynchronous operations |
| ENOMEM | Not enough space to clone store |
Return a random key from the key/value store store.
int ark_random(ark, kbuflen, klen, kbuf)
ARK * ark;
uint64_t kbuflen;
int64_t * klen;
void * kbuf;
The ark_random API will return a random key found in the store based on the handle, ark, in the buffer, kbuf, and the size of the key in klen, as long as the size is less than the size of the kbuf, kbuflen.
| Parameter | Description |
| ark | Handle respresenting the key/value store store |
| kbuflen | Length of the kbuf parameter. |
| klen | Size of the key returned in kbuf |
| kbuf | Buffer to hold the key |
Upon successful completion, ark_random will 0. Otherwise, ark_random will return the following error codes:
| Error | Reason |
| EINVAL | Invalid parameter |
Return the count of the number of keys in the key/value store store
int ark_count(ark, int *count)
ARK * ark;
int * count;
The ark_count API will return a the total number of keys in the store based on the handle, ark**,** and store the result in the count parameter.
| Parameter | Description |
| ark | Handle representing the key/value store instance. |
| count | Number of keys found in the key/value store. |
Upon successful completion, ark_count will return 0. Otherwise, a non-zero error code will be returned:
| Error | Reason |
| EINVAL | Invalid parameter |