UCP Data type routines

Data Structures
struct	ucp_dt_iov
	Structure for scatter-gather I/O. More...
struct	ucp_generic_dt_ops
	UCP generic data type descriptor. More...
struct	ucp_datatype_attr
	UCP datatype attributes. More...

Macros
#define	ucp_dt_make_contig(_elem_size)    (((ucp_datatype_t)(_elem_size) << UCP_DATATYPE_SHIFT) | UCP_DATATYPE_CONTIG)
	Generate an identifier for contiguous data type.
#define	ucp_dt_make_iov()   ((ucp_datatype_t)UCP_DATATYPE_IOV)
	Generate an identifier for Scatter-gather IOV data type.

Typedefs
typedef struct ucp_dt_iov	ucp_dt_iov_t
	Structure for scatter-gather I/O.
typedef struct ucp_generic_dt_ops	ucp_generic_dt_ops_t
	UCP generic data type descriptor.
typedef struct ucp_datatype_attr	ucp_datatype_attr_t
	UCP datatype attributes.

Enumerations
enum	ucp_dt_type {   UCP_DATATYPE_CONTIG = 0 , UCP_DATATYPE_STRIDED = 1 , UCP_DATATYPE_IOV = 2 , UCP_DATATYPE_GENERIC = 7 ,   UCP_DATATYPE_SHIFT = 3 , UCP_DATATYPE_CLASS_MASK = UCS_MASK(UCP_DATATYPE_SHIFT) }
	UCP data type classification. More...
enum	ucp_datatype_attr_field { UCP_DATATYPE_ATTR_FIELD_PACKED_SIZE = UCS_BIT(0) , UCP_DATATYPE_ATTR_FIELD_BUFFER = UCS_BIT(1) , UCP_DATATYPE_ATTR_FIELD_COUNT = UCS_BIT(2) }
	UCP datatype attributes field mask. More...

Functions
ucs_status_t	ucp_dt_create_generic (const ucp_generic_dt_ops_t *ops, void *context, ucp_datatype_t *datatype_p)
	Create a generic datatype.
void	ucp_dt_destroy (ucp_datatype_t datatype)
	Destroy a datatype and release its resources.
ucs_status_t	ucp_dt_query (ucp_datatype_t datatype, ucp_datatype_attr_t *attr)
	Query attributes of a datatype.

Variables
void *(*	ucp_generic_dt_ops::start_pack )(void *context, const void *buffer, size_t count)
	Start a packing request.
void *(*	ucp_generic_dt_ops::start_unpack )(void *context, void *buffer, size_t count)
	Start an unpacking request.
size_t(*	ucp_generic_dt_ops::packed_size )(void *state)
	Get the total size of packed data.
size_t(*	ucp_generic_dt_ops::pack )(void *state, size_t offset, void *dest, size_t max_length)
	Pack data.
ucs_status_t(*	ucp_generic_dt_ops::unpack )(void *state, size_t offset, const void *src, size_t length)
	Unpack data.
void(*	ucp_generic_dt_ops::finish )(void *state)
	Finish packing/unpacking.

Detailed Description

UCP Data type routines

---

Data Structure Documentation

ucp_dt_iov

struct ucp_dt_iov

This structure is used to specify a list of buffers which can be used within a single data transfer function call. This list should remain valid until the data transfer request is completed.

Note

If length is zero, the memory pointed to by buffer will not be accessed. Otherwise, buffer must point to valid memory.

Examples

ucp_client_server.c.

Data Fields
void *	buffer	Pointer to a data buffer
size_t	length	Length of the buffer in bytes

ucp_datatype_attr

struct ucp_datatype_attr

This structure provides attributes of a UCP datatype.

Data Fields
uint64_t	field_mask	Mask of valid fields in this structure, using bits from ucp_datatype_attr_field. Fields not specified in this mask will be ignored. Provides ABI compatibility with respect to adding new fields.
size_t	packed_size	Packed size of the given datatype. (output parameter)
const void *	buffer	Pointer to a data buffer of the associated data type. This field is optional. If UCP_DATATYPE_ATTR_FIELD_BUFFER is not set in field_mask, this field defaults to NULL.
size_t	count	Number of elements in buffer. This value is optional. If UCP_DATATYPE_ATTR_FIELD_COUNT is not set in field_mask, the value of this field defaults to 1.

Macro Definition Documentation

ucp_dt_make_contig

#define ucp_dt_make_contig

(

_elem_size

)

(((ucp_datatype_t)(_elem_size) << UCP_DATATYPE_SHIFT) | UCP_DATATYPE_CONTIG)

This macro creates an identifier for contiguous datatype that is defined by the size of the basic element.

Parameters

[in]

_elem_size

Size of the basic element of the type.

Returns

Data-type identifier.

Note

In case of partial receive, the buffer will be filled with integral count of elements.

Examples

ucp_client_server.c, and ucp_hello_world.c.

ucp_dt_make_iov

#define ucp_dt_make_iov

(

)

((ucp_datatype_t)UCP_DATATYPE_IOV)

This macro creates an identifier for datatype of scatter-gather list with multiple pointers

Returns

Data-type identifier.

Note

In the event of partial receive, ucp_dt_iov_t::buffer can be filled with any number of bytes according to its ucp_dt_iov_t::length.

Typedef Documentation

ucp_dt_iov_t

typedef struct ucp_dt_iov ucp_dt_iov_t

This structure is used to specify a list of buffers which can be used within a single data transfer function call. This list should remain valid until the data transfer request is completed.

Note

If length is zero, the memory pointed to by buffer will not be accessed. Otherwise, buffer must point to valid memory.

ucp_generic_dt_ops_t

typedef struct ucp_generic_dt_ops ucp_generic_dt_ops_t

This structure provides a generic datatype descriptor that is used for definition of application defined datatypes.

Typically, the descriptor is used for an integration with datatype engines implemented within MPI and SHMEM implementations.

Note

In case of partial receive, any amount of received data is acceptable which matches buffer size.

ucp_datatype_attr_t

typedef struct ucp_datatype_attr ucp_datatype_attr_t

This structure provides attributes of a UCP datatype.

Enumeration Type Documentation

ucp_dt_type

enum ucp_dt_type

The enumeration list describes the datatypes supported by UCP.

Enumerator
UCP_DATATYPE_CONTIG	Contiguous datatype
UCP_DATATYPE_STRIDED	Strided datatype
UCP_DATATYPE_IOV	Scatter-gather list with multiple pointers
UCP_DATATYPE_GENERIC	Generic datatype with user-defined pack/unpack routines
UCP_DATATYPE_SHIFT	Number of bits defining the datatype classification
UCP_DATATYPE_CLASS_MASK	Data-type class mask

ucp_datatype_attr_field

enum ucp_datatype_attr_field

The enumeration allows specifying which fields in ucp_datatype_attr_t are present and which datatype attributes are queried.

Enumerator
UCP_DATATYPE_ATTR_FIELD_PACKED_SIZE	ucp_datatype_attr_t::packed_size field is queried.
UCP_DATATYPE_ATTR_FIELD_BUFFER	ucp_datatype_attr_t::buffer field is set.
UCP_DATATYPE_ATTR_FIELD_COUNT	ucp_datatype_attr_t::count field is set.

Function Documentation

ucp_dt_create_generic()

ucs_status_t ucp_dt_create_generic	(	const ucp_generic_dt_ops_t *	ops,
		void *	context,
		ucp_datatype_t *	datatype_p )

This routine create a generic datatype object. The generic datatype is described by the ops object which provides a table of routines defining the operations for generic datatype manipulation. Typically, generic datatypes are used for integration with datatype engines provided with MPI implementations (MPICH, Open MPI, etc). The application is responsible for releasing the datatype_p object using ucp_dt_destroy() routine.

Parameters

[in]	ops	Generic datatype function table as defined by ucp_generic_dt_ops_t .
[in]	context	Application defined context passed to this routine. The context is passed as a parameter to the routines in the ops table.
[out]	datatype_p	A pointer to datatype object.

Returns

Error code as defined by ucs_status_t

ucp_dt_destroy()

void ucp_dt_destroy

(

ucp_datatype_t

datatype

)

This routine destroys the datatype object and releases any resources that are associated with the object. The datatype object must be allocated using ucp_dt_create_generic() routine.

Warning

• Once the datatype object is released an access to this object may cause an undefined failure.

Parameters

[in]

datatype

Datatype object to destroy.

ucp_dt_query()

ucs_status_t ucp_dt_query	(	ucp_datatype_t	datatype,
		ucp_datatype_attr_t *	attr )

This routine fetches information about the attributes of a datatype. When UCP_DATATYPE_ATTR_FIELD_PACKED_SIZE is set in field_mask of attr, the field packed_size is set to the packed size (bytes) of the datatype.

Parameters

[in]	datatype	Datatype object to query.
[in,out]	attr	Filled with attributes of the datatype.

Returns

Error code as defined by ucs_status_t

Variable Documentation

start_pack

void *(* ucp_generic_dt_ops::start_pack) (void *context, const void *buffer, size_t count)

The pointer refers to application defined start-to-pack routine. It will be called from the ucp_tag_send_nb routine.

Parameters

[in]	context	User-defined context.
[in]	buffer	Buffer to pack.
[in]	count	Number of elements to pack into the buffer.

Returns

A custom state that is passed to the following pack() routine.

start_unpack

void *(* ucp_generic_dt_ops::start_unpack) (void *context, void *buffer, size_t count)

The pointer refers to application defined start-to-unpack routine. It will be called from the ucp_tag_recv_nb routine.

Parameters

[in]	context	User-defined context.
[in]	buffer	Buffer to unpack to.
[in]	count	Number of elements to unpack in the buffer.

Returns

A custom state that is passed later to the following unpack() routine.

packed_size

size_t(* ucp_generic_dt_ops::packed_size) (void *state)

The pointer refers to user defined routine that returns the size of data in a packed format.

Parameters

[in]

state

State as returned by start_pack() routine.

Returns

The size of the data in a packed form.

pack

size_t(* ucp_generic_dt_ops::pack) (void *state, size_t offset, void *dest, size_t max_length)

The pointer refers to application defined pack routine.

Parameters

[in]	state	State as returned by start_pack() routine.
[in]	offset	Virtual offset in the output stream.
[in]	dest	Destination buffer to pack the data.
[in]	max_length	Maximum length to pack.

Returns

The size of the data that was written to the destination buffer. Must be less than or equal to max_length.

unpack

ucs_status_t(* ucp_generic_dt_ops::unpack) (void *state, size_t offset, const void *src, size_t length)

The pointer refers to application defined unpack routine.

Parameters

[in]	state	State as returned by start_unpack() routine.
[in]	offset	Virtual offset in the input stream.
[in]	src	Source to unpack the data from.
[in]	length	Length to unpack.

Returns

UCS_OK or an error if unpacking failed.

finish

void(* ucp_generic_dt_ops::finish) (void *state)

The pointer refers to application defined finish routine.

Parameters

[in]

state

State as returned by start_pack() and start_unpack() routines.