DAOS API (v2.1 - dev)
Loading...
Searching...
No Matches
daos_kv.h File Reference
#include <daos_types.h>
#include <daos_obj.h>

Go to the source code of this file.

Macros

#define DAOS_COND_KEY_INSERT   DAOS_COND_DKEY_INSERT
 
#define DAOS_COND_KEY_UPDATE   DAOS_COND_DKEY_UPDATE
 
#define DAOS_COND_KEY_GET   DAOS_COND_DKEY_FETCH
 
#define DAOS_COND_KEY_REMOVE   DAOS_COND_PUNCH
 

Functions

int daos_kv_open (daos_handle_t coh, daos_obj_id_t oid, unsigned int mode, daos_handle_t *oh, daos_event_t *ev)
 
int daos_kv_close (daos_handle_t oh, daos_event_t *ev)
 
int daos_kv_destroy (daos_handle_t oh, daos_handle_t th, daos_event_t *ev)
 
int daos_kv_put (daos_handle_t oh, daos_handle_t th, uint64_t flags, const char *key, daos_size_t size, const void *buf, daos_event_t *ev)
 
int daos_kv_get (daos_handle_t oh, daos_handle_t th, uint64_t flags, const char *key, daos_size_t *size, void *buf, daos_event_t *ev)
 
int daos_kv_remove (daos_handle_t oh, daos_handle_t th, uint64_t flags, const char *key, daos_event_t *ev)
 
int daos_kv_list (daos_handle_t oh, daos_handle_t th, uint32_t *nr, daos_key_desc_t *kds, d_sg_list_t *sgl, daos_anchor_t *anchor, daos_event_t *ev)
 

Detailed Description

DAOS flat Key-Value Store

The KV API simplify the DAOS 2 key-level object into a simple KV interface for users who are just interested in a traditional KV store API.

Definition in file daos_kv.h.

Macro Definition Documentation

◆ DAOS_COND_KEY_GET

#define DAOS_COND_KEY_GET   DAOS_COND_DKEY_FETCH

Conditional Op: Get key if it exists, fail otherwise

Definition at line 30 of file daos_kv.h.

◆ DAOS_COND_KEY_INSERT

#define DAOS_COND_KEY_INSERT   DAOS_COND_DKEY_INSERT

Conditional Op: Insert key if it doesn't exist, fail otherwise

Definition at line 26 of file daos_kv.h.

◆ DAOS_COND_KEY_REMOVE

#define DAOS_COND_KEY_REMOVE   DAOS_COND_PUNCH

Conditional Op: Remove key if it exists, fail otherwise

Definition at line 32 of file daos_kv.h.

◆ DAOS_COND_KEY_UPDATE

#define DAOS_COND_KEY_UPDATE   DAOS_COND_DKEY_UPDATE

Conditional Op: Update key if it exists, fail otherwise

Definition at line 28 of file daos_kv.h.

Function Documentation

◆ daos_kv_close()

int daos_kv_close ( daos_handle_t oh,
daos_event_t * ev )

Close an opened KV object.

Parameters
[in]ohKV object open handle.
[in]evCompletion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL.
Returns
These values will be returned by ev::ev_error in non-blocking mode: 0 Success -DER_NO_HDL Invalid object open handle

◆ daos_kv_destroy()

int daos_kv_destroy ( daos_handle_t oh,
daos_handle_t th,
daos_event_t * ev )

Destroy the kV object by punching all data (keys) in the kv object. daos_obj_punch() is called underneath. The oh still needs to be closed with a call to daos_kv_close().

Parameters
[in]ohKV object open handle.
[in]thTransaction handle.
[in]evCompletion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL.
Returns
These values will be returned by ev::ev_error in non-blocking mode: 0 Success -DER_NO_HDL Invalid object open handle -DER_INVAL Invalid parameter

◆ daos_kv_get()

int daos_kv_get ( daos_handle_t oh,
daos_handle_t th,
uint64_t flags,
const char * key,
daos_size_t * size,
void * buf,
daos_event_t * ev )

Fetch value of a key.

Parameters
[in]ohObject open handle.
[in]thTransaction handle.
[in]flagsFetch flags.
[in]keykey associated with the update operation.
[in,out]size[in]: Size of the user buf. if the size is unknown, set to DAOS_REC_ANY). [out]: The actual size of the value.
[out]bufPointer to user buffer. If NULL, only size is returned.
[in]evCompletion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL.
Returns
These values will be returned by ev::ev_error in non-blocking mode: 0 Success -DER_NO_HDL Invalid object open handle -DER_INVAL Invalid parameter -DER_NO_PERM Permission denied -DER_UNREACH Network is unreachable -DER_REC2BIG Record does not fit in buffer -DER_EP_RO Epoch is read-only

◆ daos_kv_list()

int daos_kv_list ( daos_handle_t oh,
daos_handle_t th,
uint32_t * nr,
daos_key_desc_t * kds,
d_sg_list_t * sgl,
daos_anchor_t * anchor,
daos_event_t * ev )

List/enumerate all keys in an object.

Parameters
[in]ohObject open handle.
[in]thTransaction handle.
[in,out]nr[in]: number of key descriptors in kds. [out]: number of returned key descriptors.
[in,out]kds[in]: preallocated array of nr key descriptors. [out]: size of each individual key.
[in]sglScatter/gather list to store the dkey list. All keys are written contiguously, with actual boundaries that can be calculated using kds.
[in,out]anchorHash anchor for the next call, it should be set to zeroes for the first call, it should not be changed by caller between calls.
[in]evCompletion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL.
Returns
These values will be returned by ev::ev_error in non-blocking mode: 0 Success -DER_NO_HDL Invalid object open handle -DER_INVAL Invalid parameter -DER_NO_PERM Permission denied -DER_UNREACH Network is unreachable -DER_EP_RO Epoch is read-only

◆ daos_kv_open()

int daos_kv_open ( daos_handle_t coh,
daos_obj_id_t oid,
unsigned int mode,
daos_handle_t * oh,
daos_event_t * ev )

Open a KV object. This is a local operation (no RPC involved). The type bits in the oid must set DAOS_OT_KV_*.

Parameters
[in]cohContainer open handle.
[in]oidObject ID. It is required that the object type be set to DAOS_OT_KV_*.
[in]modeOpen mode: DAOS_OO_RO/RW
[out]ohReturned kv object open handle.
[in]evCompletion event, it is optional and can be NULL. The function will run in blocking mode if ev is NULL.
Returns
These values will be returned by ev::ev_error in non-blocking mode: 0 Success -DER_NO_HDL Invalid container handle -DER_INVAL Invalid parameter

◆ daos_kv_put()

int daos_kv_put ( daos_handle_t oh,
daos_handle_t th,
uint64_t flags,
const char * key,
daos_size_t size,
const void * buf,
daos_event_t * ev )

Insert or update a single object KV pair. If a value existed before it will be overwritten (punched first if not previously an atomic value) with the new atomic value described by the sgl.

Parameters
[in]ohObject open handle.
[in]thTransaction handle.
[in]flagsUpdate flags.
[in]keyKey associated with the update operation.
[in]sizeSize of the buffer to be inserted as an atomic val.
[in]bufPointer to user buffer of the atomic value.
[in]evCompletion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL.
Returns
These values will be returned by ev::ev_error in non-blocking mode: 0 Success -DER_NO_HDL Invalid object open handle -DER_INVAL Invalid parameter -DER_NO_PERM Permission denied -DER_UNREACH Network is unreachable -DER_EP_RO Epoch is read-only

◆ daos_kv_remove()

int daos_kv_remove ( daos_handle_t oh,
daos_handle_t th,
uint64_t flags,
const char * key,
daos_event_t * ev )

Remove a Key and it's value from the KV store

Parameters
[in]ohObject open handle.
[in]thTransaction handle.
[in]flagsRemove flags.
[in]keyKey to be punched/removed.
[in]evCompletion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL.
Returns
These values will be returned by ev::ev_error in non-blocking mode: 0 Success -DER_NO_HDL Invalid object open handle -DER_INVAL Invalid parameter -DER_NO_PERM Permission denied -DER_UNREACH Network is unreachable -DER_EP_RO Epoch is read-only