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

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. More...
#define	ucp_dt_make_iov()   (UCP_DATATYPE_IOV)
	Generate an identifier for Scatter-gather IOV data type. More...

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

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

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. More...
void	ucp_dt_destroy (ucp_datatype_t datatype)
	Destroy a datatype and release its resources. More...

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

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.

Note

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

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

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_hello_world.c.

ucp_dt_make_iov

#define ucp_dt_make_iov

(

)

(UCP_DATATYPE_IOV)

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

Returns

Data-type identifier.

Note

In case 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.

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.

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

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.

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 to pack the data to.
[in]	max_length	Maximal 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.