#include <daos_types.h>
#include <daos_obj.h>
#include <daos_obj_class.h>
Go to the source code of this file.
|
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) |
|
DAOS Array
The DAOS Array API provides a 1-D array implementation over the DAOS object data model.
Definition in file daos_array.h.
◆ daos_array_close()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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