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]	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