UCX 1.16
Unified Communication X
Loading...
Searching...
No Matches

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

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

This structure provides attributes of a UCP datatype.

Enumeration Type Documentation

◆ 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

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]opsGeneric datatype function table as defined by ucp_generic_dt_ops_t .
[in]contextApplication defined context passed to this routine. The context is passed as a parameter to the routines in the ops table.
[out]datatype_pA 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]datatypeDatatype 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]datatypeDatatype object to query.
[in,out]attrFilled 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]contextUser-defined context.
[in]bufferBuffer to pack.
[in]countNumber 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]contextUser-defined context.
[in]bufferBuffer to unpack to.
[in]countNumber 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]stateState 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]stateState as returned by start_pack() routine.
[in]offsetVirtual offset in the output stream.
[in]destDestination buffer to pack the data.
[in]max_lengthMaximum 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]stateState as returned by start_unpack() routine.
[in]offsetVirtual offset in the input stream.
[in]srcSource to unpack the data from.
[in]lengthLength 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]stateState as returned by start_pack() and start_unpack() routines.