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

| DAOS API (v2.1 - dev)

Loading...
Searching...
No Matches
daos_array.h File Reference

Go to the source code of this file.

## Data Structures
struct | daos_range_t
struct | daos_array_iod_t
struct | daos_array_stbuf_t

## Functions
int | daos_array_create (daos_handle_t coh, daos_obj_id_t oid, daos_handle_t th, daos_size_t cell_size, daos_size_t chunk_size, daos_handle_t *oh, daos_event_t *ev)
int | daos_array_open (daos_handle_t coh, daos_obj_id_t oid, daos_handle_t th, unsigned int mode, daos_size_t *cell_size, daos_size_t *chunk_size, daos_handle_t *oh, daos_event_t *ev)
int | daos_array_open_with_attr (daos_handle_t coh, daos_obj_id_t oid, daos_handle_t th, unsigned int mode, daos_size_t cell_size, daos_size_t chunk_size, daos_handle_t *oh, daos_event_t *ev)
int | daos_array_local2global (daos_handle_t oh, d_iov_t *glob)
int | daos_array_global2local (daos_handle_t coh, d_iov_t glob, unsigned int mode, daos_handle_t *oh)
int | daos_array_close (daos_handle_t oh, daos_event_t *ev)
int | daos_array_read (daos_handle_t oh, daos_handle_t th, daos_array_iod_t *iod, d_sg_list_t *sgl, daos_event_t *ev)
int | daos_array_write (daos_handle_t oh, daos_handle_t th, daos_array_iod_t *iod, d_sg_list_t *sgl, daos_event_t *ev)
int | daos_array_get_size (daos_handle_t oh, daos_handle_t th, daos_size_t *size, daos_event_t *ev)
int | daos_array_stat (daos_handle_t oh, daos_handle_t th, daos_array_stbuf_t *stbuf, daos_event_t *ev)
int | daos_array_set_size (daos_handle_t oh, daos_handle_t th, daos_size_t size, daos_event_t *ev)
int | daos_array_destroy (daos_handle_t oh, daos_handle_t th, daos_event_t *ev)
int | daos_array_punch (daos_handle_t oh, daos_handle_t th, daos_array_iod_t *iod, daos_event_t *ev)
int | daos_array_get_attr (daos_handle_t oh, daos_size_t *chunk_size, daos_size_t *cell_size)
int | daos_array_update_chunk_size (daos_handle_t oh, daos_size_t chunk_size)

## Detailed Description

DAOS Array

The DAOS Array API provides a 1-D array implementation over the DAOS object data model.

Definition in file daos_array.h.

## Function Documentation

## ◆ daos_array_close()

int daos_array_close | ( | daos_handle_t | oh,
|  | daos_event_t * | ev )

Close an opened array object.

Parameters

  [in] | oh | Array 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_array_create()

int daos_array_create | ( | daos_handle_t | coh,
|  | daos_obj_id_t | oid,
|  | daos_handle_t | th,
|  | daos_size_t | cell_size,
|  | daos_size_t | chunk_size,
|  | daos_handle_t * | oh,
|  | daos_event_t * | ev )

Create an Array object. This opens a DAOS object and adds metadata under a special akey to define the cell size and chunk size. Further access to that object using the handle will use that metadata to store the array elements.

The metadata of the array is stored under a special AKEY in DKEY 0. This means that this is a generic array object with it's metadata tracked in the DAOS object. The feat bits in the oid must set DAOS_OT_ARRAY,DAOS_OT_ARRAY_ATTR or DAOS_OT_ARRAY_BYTE. If the feat bits does not set DAOS_OT_ARRAY, the user would be responsible for remembering the array metadata since DAOS will not store those, and should not call this API since nothing will be written to the array object. daos_array_open_with_attrs() can be used to get an array OH in that case to access with the Array APIs.

Parameters

  [in] | coh | Container open handle.
  [in] | oid | Object ID. It is required that the object type be set to DAOS_OT_ARRAY.
  [in] | th | Transaction handle.
  [in] | cell_size | Record size of the array.
  [in] | chunk_size | Number of contiguous records to store per DKey before moving to a different dkey.
  [out] | oh | Returned array 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 -DER_EXIST Array already exists -DER_UNREACH Network is unreachable

## ◆ daos_array_destroy()

int daos_array_destroy | ( | daos_handle_t | oh,
|  | daos_handle_t | th,
|  | daos_event_t * | ev )

Destroy the array object by punching all data (keys) in the array object including the metadata associated with the array. daos_obj_punch() is called underneath. The oh still needs to be closed with a call to daos_array_close(), but any other access with that handle, or other array open handles, will fail. The destroy will happen regardless of any open handle, so it's the user responsibility to ensure that there is no further access to the array before the destroy is called.

Parameters

  [in] | oh | Array 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 -DER_UNREACH Network is unreachable

## ◆ daos_array_get_attr()

int daos_array_get_attr | ( | daos_handle_t | oh,
|  | daos_size_t * | chunk_size,
|  | daos_size_t * | cell_size )

Retrieve array cell and chunk size from an open handle.

Parameters

  [in] | oh | Array object open handle.
  [out] | chunk_size | Chunk size of the array.
  [out] | cell_size | Cell size of the array.

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_array_get_size()

int daos_array_get_size | ( | daos_handle_t | oh,
|  | daos_handle_t | th,
|  | daos_size_t * | size,
|  | daos_event_t * | ev )

Query the number of records in the array object.

Parameters

  [in] | oh | Array object open handle.
  [in] | th | Transaction handle.
  [out] | size | Returned array size (number of records).
  [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_UNREACH Network is unreachable

## ◆ daos_array_global2local()

int daos_array_global2local | ( | daos_handle_t | coh,
|  | d_iov_t | glob,
|  | unsigned int | mode,
|  | daos_handle_t * | oh )

Create a local array open handle for global representation data. This handle has to be closed with daos_array_close().

Parameters

  [in] | coh | Container open handle the array belongs to
  [in] | glob | Global (shared) representation of a collective handle to be extracted
  [in] | mode | Option to change the object open mode. Pass 0 to inherit the global mode.
  [out] | oh | Returned local array open handle

Returns
  These values will be returned: non-blocking mode: 0 Success -DER_INVAL Invalid parameter -DER_NO_HDL Container handle is nonexistent

## ◆ daos_array_local2global()

int daos_array_local2global | ( | daos_handle_t | oh,
|  | d_iov_t * | glob )

Convert a local array handle to global representation data which can be shared with peer processes. If glob->iov_buf is set to NULL, the actual size of the global handle is returned through glob->iov_buf_len. This function does not involve any communication and does not block.

Parameters

  [in] | oh | valid local array object open handle to be shared
  [out] | glob | pointer to iov of the buffer to store handle information

Returns
  These values will be returned: non-blocking mode: 0 Success -DER_INVAL Invalid parameter -DER_NO_HDL Array handle is nonexistent -DER_TRUNC Buffer in glob is too short, larger buffer required. In this case the required buffer size is returned through glob->iov_buf_len.

## ◆ daos_array_open()

int daos_array_open | ( | daos_handle_t | coh,
|  | daos_obj_id_t | oid,
|  | daos_handle_t | th,
|  | unsigned int | mode,
|  | daos_size_t * | cell_size,
|  | daos_size_t * | chunk_size,
|  | daos_handle_t * | oh,
|  | daos_event_t * | ev )

Open an Array object. If the array has not been created before (no array metadata exists), this will fail.

Parameters

  [in] | coh | Container open handle.
  [in] | oid | Object ID. It is required that the feat for dkey type be set to DAOS_OT_ARRAY.
  [in] | th | Transaction handle.
  [in] | mode | Open mode: DAOS_OO_RO/RW
  [out] | cell_size | Record size of the array.
  [out] | chunk_size | Contiguous bytes to store per DKey before moving to a different dkey.
  [out] | oh | Returned array 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 -DER_NO_PERM Permission denied -DER_NONEXIST Cannot find object -DER_UNREACH Network is unreachable

## ◆ daos_array_open_with_attr()

int daos_array_open_with_attr | ( | daos_handle_t | coh,
|  | daos_obj_id_t | oid,
|  | daos_handle_t | th,
|  | unsigned int | mode,
|  | daos_size_t | cell_size,
|  | daos_size_t | chunk_size,
|  | daos_handle_t * | oh,
|  | daos_event_t * | ev )

Open an Array object with the array attributes specified by the user. This is the same as the create call if the object does not exist, except that nothing is updated in the object, and the API just returns an OH to the user. If the array was accessed with different cell_size and chunk_size before, accessing it again will introduce corruption in the array data.

Parameters

  [in] | coh | Container open handle.
  [in] | oid | Object ID. It is required that the object type to be be set to DAOS_OT_ARRAY_ATTR or DAOS_OT_ARRAY_BYTE.
  [in] | th | Transaction handle.
  [in] | mode | Open mode: DAOS_OO_RO/RW
  [in] | cell_size | Record size of the array.
  [in] | chunk_size | Contiguous bytes to store per DKey before moving to a different dkey.
  [out] | oh | Returned array 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 -DER_NO_PERM Permission denied

## ◆ daos_array_punch()

int daos_array_punch | ( | daos_handle_t | oh,
|  | daos_handle_t | th,
|  | daos_array_iod_t * | iod,
|  | daos_event_t * | ev )

Punch a hole in the array indicated by the range in the iod.

Parameters

  [in] | oh | Array object open handle.
  [in] | th | Transaction handle.
  [in] | iod | IO descriptor of ranges to punch in the array.
  [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_UNREACH Network is unreachable

## ◆ daos_array_read()

int daos_array_read | ( | daos_handle_t | oh,
|  | daos_handle_t | th,
|  | daos_array_iod_t * | iod,
|  | d_sg_list_t * | sgl,
|  | daos_event_t * | ev )

Read data from an array object.

Parameters

  [in] | oh | Array object open handle.
  [in] | th | Transaction handle.
  [in] | iod | IO descriptor of ranges to read from the array.
  [in] | sgl | A scatter/gather list (sgl) to the store array data. Buffer sizes do not have to match the individual range sizes as long as the total size does. User allocates the buffer(s) and sets the length of each buffer.
  [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_UNREACH Network is unreachable -DER_REC2BIG Record is too large and can't be fit into output buffer

## ◆ daos_array_set_size()

int daos_array_set_size | ( | daos_handle_t | oh,
|  | daos_handle_t | th,
|  | daos_size_t | size,
|  | daos_event_t * | ev )

Set the array size (truncate) in records. If array is shrinking, we punch dkeys/records above the required size. If the array is expanding, we insert 1 record at the corresponding size. This is NOT equivalent to an allocate.

Parameters

  [in] | oh | Array object open handle.
  [in] | th | Transaction handle.
  [in] | size | Size (number of records) to set array to.
  [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_UNREACH Network is unreachable

## ◆ daos_array_stat()

int daos_array_stat | ( | daos_handle_t | oh,
|  | daos_handle_t | th,
|  | daos_array_stbuf_t * | stbuf,
|  | daos_event_t * | ev )

Stat array to retrieve size and mtime.

Parameters

  [in] | oh | Array object open handle.
  [in] | th | Transaction handle.
  [out] | stbuf | Returned stat info.
  [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_UNREACH Network is unreachable

## ◆ daos_array_update_chunk_size()

int daos_array_update_chunk_size | ( | daos_handle_t | oh,
|  | daos_size_t | chunk_size )

Update the chunk size for an open array handle. Users normally should not use this API.

Parameters

  [in] | oh | Array object open handle.
  [in] | chunk_size | Chunk size of the array.

Returns
  These values will be returned by ev::ev_error in non-blocking mode: 0 Success -DER_NO_HDL Invalid object open handle

## ◆ daos_array_write()

int daos_array_write | ( | daos_handle_t | oh,
|  | daos_handle_t | th,
|  | daos_array_iod_t * | iod,
|  | d_sg_list_t * | sgl,
|  | daos_event_t * | ev )

Write data to an array object.

Parameters

  [in] | oh | Array object open handle.
  [in] | th | Transaction handle.
  [in] | iod | IO descriptor of ranges to write to the array.
  [in] | sgl | A scatter/gather list (sgl) to the store array data. Buffer sizes do not have to match the individual range sizes as long as the total size does.
  [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_UNREACH Network is unreachable -DER_REC2BIG Record is too large and can't be fit into output buffer