DAOS API: src/include/daos_kv.h File Reference

| 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] | oh | KV object open handle.
  [in] | ev | Completion 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] | oh | KV object open handle.
  [in] | th | Transaction handle.
  [in] | ev | Completion 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] | oh | Object open handle.
  [in] | th | Transaction handle.
  [in] | flags | Fetch flags.
  [in] | key | key 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] | buf | Pointer to user buffer. If NULL, only size is returned.
  [in] | ev | Completion 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] | oh | Object open handle.
  [in] | th | Transaction 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] | sgl | Scatter/gather list to store the dkey list. All keys are written contiguously, with actual boundaries that can be calculated using kds.
  [in,out] | anchor | Hash 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] | ev | Completion 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] | coh | Container open handle.
  [in] | oid | Object ID. It is required that the object type be set to DAOS_OT_KV_*.
  [in] | mode | Open mode: DAOS_OO_RO/RW
  [out] | oh | Returned kv object open handle.
  [in] | ev | Completion 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] | oh | Object open handle.
  [in] | th | Transaction handle.
  [in] | flags | Update flags.
  [in] | key | Key associated with the update operation.
  [in] | size | Size of the buffer to be inserted as an atomic val.
  [in] | buf | Pointer to user buffer of the atomic value.
  [in] | ev | Completion 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] | oh | Object open handle.
  [in] | th | Transaction handle.
  [in] | flags | Remove flags.
  [in] | key | Key to be punched/removed.
  [in] | ev | Completion 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