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

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]ohArray 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_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]cohContainer open handle.
[in]oidObject ID. It is required that the object type be set to DAOS_OT_ARRAY.
[in]thTransaction handle.
[in]cell_sizeRecord size of the array.
[in]chunk_sizeNumber of contiguous records to store per DKey before moving to a different dkey.
[out]ohReturned array 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 -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]ohArray 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 -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]ohArray object open handle.
[out]chunk_sizeChunk size of the array.
[out]cell_sizeCell 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]ohArray object open handle.
[in]thTransaction handle.
[out]sizeReturned array size (number of records).
[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_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]cohContainer open handle the array belongs to
[in]globGlobal (shared) representation of a collective handle to be extracted
[in]modeOption to change the object open mode. Pass 0 to inherit the global mode.
[out]ohReturned 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]ohvalid local array object open handle to be shared
[out]globpointer 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]cohContainer open handle.
[in]oidObject ID. It is required that the feat for dkey type be set to DAOS_OT_ARRAY.
[in]thTransaction handle.
[in]modeOpen mode: DAOS_OO_RO/RW
[out]cell_sizeRecord size of the array.
[out]chunk_sizeContiguous bytes to store per DKey before moving to a different dkey.
[out]ohReturned array 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 -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]cohContainer open handle.
[in]oidObject ID. It is required that the object type to be be set to DAOS_OT_ARRAY_ATTR or DAOS_OT_ARRAY_BYTE.
[in]thTransaction handle.
[in]modeOpen mode: DAOS_OO_RO/RW
[in]cell_sizeRecord size of the array.
[in]chunk_sizeContiguous bytes to store per DKey before moving to a different dkey.
[out]ohReturned array 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 -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]ohArray object open handle.
[in]thTransaction handle.
[in]iodIO descriptor of ranges to punch in the array.
[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_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]ohArray object open handle.
[in]thTransaction handle.
[in]iodIO descriptor of ranges to read from the array.
[in]sglA 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]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_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]ohArray object open handle.
[in]thTransaction handle.
[in]sizeSize (number of records) to set array to.
[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_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]ohArray object open handle.
[in]thTransaction handle.
[out]stbufReturned stat info.
[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_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]ohArray object open handle.
[in]chunk_sizeChunk 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]ohArray object open handle.
[in]thTransaction handle.
[in]iodIO descriptor of ranges to write to the array.
[in]sglA 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]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_UNREACH Network is unreachable -DER_REC2BIG Record is too large and can't be fit into output buffer