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

| DAOS API (v2.1 - dev)

Loading...
Searching...
No Matches
daos_api.h File Reference
`#include <daos_types.h>`

Go to the source code of this file.

## Enumerations
enum | { DAOS_TF_RDONLY = (1 << 0) , DAOS_TF_ZERO_COPY = (1 << 1) }

## Functions
d_rank_list_t * | daos_rank_list_parse (const char *str, const char *sep)
int | daos_tx_open (daos_handle_t coh, daos_handle_t *th, uint64_t flags, daos_event_t *ev)
int | daos_tx_commit (daos_handle_t th, daos_event_t *ev)
int | daos_tx_open_snap (daos_handle_t coh, daos_epoch_t epoch, daos_handle_t *th, daos_event_t *ev)
int | daos_tx_abort (daos_handle_t th, daos_event_t *ev)
int | daos_tx_close (daos_handle_t th, daos_event_t *ev)
int | daos_tx_restart (daos_handle_t th, daos_event_t *ev)
int | daos_tx_hdl2epoch (daos_handle_t th, daos_epoch_t *epoch)
int | daos_hlc2timespec (uint64_t hlc, struct timespec *ts)
int | daos_hlc2timestamp (uint64_t hlc, time_t *ts)

## Detailed Description

DAOS API methods

Definition in file daos_api.h.

## Enumeration Type Documentation

## ◆ anonymous enum

anonymous enum

Flags for daos_tx_open

Enumerator
DAOS_TF_RDONLY | The transaction is read only.
DAOS_TF_ZERO_COPY | Do not copy caller data buffers during modifications associated with the transaction. The buffers must remain unchanged until the daos_tx_commit operation for the transaction completes. Key buffers are always copied, regardless of this flag. They can be released or repurposed after corresponding operations complete.

Definition at line 22 of file daos_api.h.

## Function Documentation

## ◆ daos_hlc2timespec()

int daos_hlc2timespec | ( | uint64_t | hlc,
|  | struct timespec * | ts )

Convert daos hybrid logical clock (HLC) time to system struct timespec.

Parameters

  [in] | hlc | 64-bit HLC value returned by libdaos API (such as found in daos_cont_info_t)
  [out] | ts | pointer to timespec structure to fill with system time converted from HLC.

Returns
  0 if Success, negative if failed.

Return values

  -DER_INVAL | Invalid parameter

## ◆ daos_hlc2timestamp()

int daos_hlc2timestamp | ( | uint64_t | hlc,
|  | time_t * | ts )

Convert daos hybrid logical clock (HLC) time to seconds timestamp.

Parameters

  [in] | hlc | 64-bit HLC value returned by libdaos API (such as found in daos_cont_info_t)
  [out] | ts | pointer to time_t value to assign with seconds since the UNIX epoch, converted from daos HLC.

Returns
  0 if Success, negative if failed.

Return values

  -DER_INVAL | Invalid parameter

## ◆ daos_rank_list_parse()

d_rank_list_t * daos_rank_list_parse | ( | const char * | str,
|  | const char * | sep )

Generate a rank list from a string with a separator argument. This is a convenience function to generate the rank list.

Parameters

  [in] | str | string with the rank list
  [in] | sep | separator of the ranks in str. dmg uses ":" as the separator.

Returns
  allocated rank list that user is responsible to free with d_rank_list_free().

## ◆ daos_tx_abort()

int daos_tx_abort | ( | daos_handle_t | th,
|  | daos_event_t * | ev )

Abort all modifications on the transaction. The transaction handle cannot be used for any new IO.

Parameters

  [in] | th | Transaction handle to abort.
  [in] | ev | Completion event, it is optional and can be NULL. The function will run in blocking mode if ev is NULL.

Returns
  0 if Success, negative if failed.

## ◆ daos_tx_close()

int daos_tx_close | ( | daos_handle_t | th,
|  | daos_event_t * | ev )

Close the transaction handle. This is a local operation, no RPC involved.

Parameters

  [in] | th | Transaction handle to free.
  [in] | ev | Completion event, it is optional and can be NULL. The function will run in blocking mode if ev is NULL.

Returns
  0 if Success, negative if failed.

## ◆ daos_tx_commit()

int daos_tx_commit | ( | daos_handle_t | th,
|  | daos_event_t * | ev )

Commit the transaction. If the operation succeeds, the transaction handle cannot be used for any new IO. If -DER_TX_RESTART is returned, the caller needs to restart the transaction with the same transaction handle, by calling daos_tx_restart, re-executing the caller code for this transaction, and calling daos_tx_commit again.

Parameters

  [in] | th | Transaction handle to commit.
  [in] | ev | Completion event, it is optional and can be NULL. The function will run in blocking mode if ev is NULL.

Returns
  0 if Success, negative if failed. Possible error values include: -DER_NO_HDL invalid transaction handle. -DER_INVAL Invalid parameter -DER_TX_RESTART transaction needs to restart (e.g., due to conflicts).

## ◆ daos_tx_hdl2epoch()

int daos_tx_hdl2epoch | ( | daos_handle_t | th,
|  | daos_epoch_t * | epoch )

Return the epoch associated with the transaction handle. An epoch may not be available at the beginning of the transaction, but one shall be available after the transaction successfully commits.

This function is specific to the current implementation. It should only be used for testing and debugging purposes.

Parameters

  [in] | th | Transaction handle.
  [out] | epoch | Returned epoch value.

Returns
  0 if Success, negative if failed.

Return values

  -DER_UNINIT | An epoch is not available yet.

## ◆ daos_tx_open()

int daos_tx_open | ( | daos_handle_t | coh,
|  | daos_handle_t * | th,
|  | uint64_t | flags,
|  | daos_event_t * | ev )

Open a transaction on a container handle. The resulting transaction handle can be used for IOs in this container that need to be committed transactionally.

Invoking operations of one TX with events from multiple event queues, including with NULL events from multiple threads, is not currently supported.

Parameters

  [in] | coh | Container handle.
  [out] | th | Returned transaction handle.
  [in] | flags | Transaction flags (DAOS_TF_RDONLY, etc.).
  [in] | ev | Completion event, it is optional and can be NULL. The function will run in blocking mode if ev is NULL.

Returns
  0 if Success, negative if failed.

## ◆ daos_tx_open_snap()

int daos_tx_open_snap | ( | daos_handle_t | coh,
|  | daos_epoch_t | epoch,
|  | daos_handle_t * | th,
|  | daos_event_t * | ev )

Create a read-only transaction from a snapshot. This does not create the snapshot, but only a read transaction to be able to read from a snapshot created with daos_cont_create_snap. If the user passes an epoch that is not snapshotted, or the snapshot was deleted, reads using that transaction may get undefined results.

Parameters

  [in] | coh | Container handle.
  [in] | epoch | Epoch of snapshot to read from.
  [out] | th | Returned read only transaction handle.
  [in] | ev | Completion event, it is optional and can be NULL. The function will run in blocking mode if ev is NULL.

Returns
  0 if Success, negative if failed.

## ◆ daos_tx_restart()

int daos_tx_restart | ( | daos_handle_t | th,
|  | daos_event_t * | ev )

Restart the transaction after encountering a -DER_TX_RESTART error. This drops all the IOs that have been issued via the transaction handle. Whether the restarted transaction observes any conflicting modifications committed after this transaction was originally opened is undefined. If callers would like to retry transactions for their own purposes, they shall open new transactions instead. This is a local operation, no RPC involved.

Parameters

  [in] | th | Transaction handle to be restarted.
  [in] | ev | Completion event, it is optional and can be NULL. The function will run in blocking mode if ev is NULL.

Returns
  0 if Success, negative if failed.