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

Data Structures

struct  ucp_lib_attr
 Lib attributes. More...
 
struct  ucp_context_attr
 Context attributes. More...
 
struct  ucp_tag_recv_info
 UCP receive information descriptor. More...
 
struct  ucp_request_param_t
 Operation parameters passed to ucp_tag_send_nbx, ucp_tag_send_sync_nbx, ucp_tag_recv_nbx, ucp_put_nbx, ucp_get_nbx, ucp_am_send_nbx and ucp_am_recv_data_nbx. More...
 
union  ucp_request_param_t.cb
 
union  ucp_request_param_t.recv_info
 

Macros

#define UCP_ENTITY_NAME_MAX   32
 Maximum size of the UCP entity name in structure of entity attributes provided by a query method.
 

Typedefs

typedef struct ucp_lib_attr ucp_lib_attr_t
 Lib attributes.
 
typedef struct ucp_context_attr ucp_context_attr_t
 Context attributes.
 
typedef struct ucp_tag_recv_info ucp_tag_recv_info_t
 UCP receive information descriptor.
 
typedef struct ucp_context * ucp_context_h
 UCP Application Context.
 
typedef void(* ucp_request_init_callback_t) (void *request)
 Request initialization callback.
 
typedef void(* ucp_request_cleanup_callback_t) (void *request)
 Request cleanup callback.
 

Enumerations

enum  ucp_params_field {
  UCP_PARAM_FIELD_FEATURES = UCS_BIT(0) , UCP_PARAM_FIELD_REQUEST_SIZE = UCS_BIT(1) , UCP_PARAM_FIELD_REQUEST_INIT = UCS_BIT(2) , UCP_PARAM_FIELD_REQUEST_CLEANUP = UCS_BIT(3) ,
  UCP_PARAM_FIELD_TAG_SENDER_MASK = UCS_BIT(4) , UCP_PARAM_FIELD_MT_WORKERS_SHARED = UCS_BIT(5) , UCP_PARAM_FIELD_ESTIMATED_NUM_EPS = UCS_BIT(6) , UCP_PARAM_FIELD_ESTIMATED_NUM_PPN = UCS_BIT(7) ,
  UCP_PARAM_FIELD_NAME = UCS_BIT(8)
}
 UCP context parameters field mask. More...
 
enum  ucp_feature {
  UCP_FEATURE_TAG = UCS_BIT(0) , UCP_FEATURE_RMA = UCS_BIT(1) , UCP_FEATURE_AMO32 = UCS_BIT(2) , UCP_FEATURE_AMO64 = UCS_BIT(3) ,
  UCP_FEATURE_WAKEUP = UCS_BIT(4) , UCP_FEATURE_STREAM = UCS_BIT(5) , UCP_FEATURE_AM = UCS_BIT(6) , UCP_FEATURE_EXPORTED_MEMH = UCS_BIT(7)
}
 UCP configuration features. More...
 
enum  ucp_lib_attr_field { UCP_LIB_ATTR_FIELD_MAX_THREAD_LEVEL = UCS_BIT(0) }
 UCP library attributes field mask. More...
 
enum  ucp_context_attr_field { UCP_ATTR_FIELD_REQUEST_SIZE = UCS_BIT(0) , UCP_ATTR_FIELD_THREAD_MODE = UCS_BIT(1) , UCP_ATTR_FIELD_MEMORY_TYPES = UCS_BIT(2) , UCP_ATTR_FIELD_NAME = UCS_BIT(3) }
 UCP context attributes field mask. More...
 

Functions

ucs_status_t ucp_lib_query (ucp_lib_attr_t *attr)
 Get attributes of the UCP library.
 
void ucp_get_version (unsigned *major_version, unsigned *minor_version, unsigned *release_number)
 Get UCP library version.
 
const char * ucp_get_version_string (void)
 Get UCP library version as a string.
 
static ucs_status_t ucp_init (const ucp_params_t *params, const ucp_config_t *config, ucp_context_h *context_p)
 UCP context initialization.
 
void ucp_cleanup (ucp_context_h context_p)
 Release UCP application context.
 
ucs_status_t ucp_context_query (ucp_context_h context_p, ucp_context_attr_t *attr)
 Get attributes specific to a particular context.
 
void ucp_context_print_info (const ucp_context_h context, FILE *stream)
 Print context information.
 

Detailed Description

Application context is a primary concept of UCP design which provides an isolation mechanism, allowing resources associated with the context to separate or share network communication context across multiple instances of applications.

This section provides a detailed description of this concept and routines associated with it.


Data Structure Documentation

◆ ucp_lib_attr

struct ucp_lib_attr

The structure defines the attributes that characterize the Library.

Data Fields
uint64_t field_mask

Mask of valid fields in this structure, using bits from ucp_lib_attr_field. Fields not specified in this mask will be ignored. Provides ABI compatibility with respect to adding new fields.

ucs_thread_mode_t max_thread_level

Maximum level of thread support of the library, which is permanent throughout the lifetime of the library. Accordingly, the user can call ucp_worker_create with appropriate ucp_worker_params_t::thread_mode. For supported thread levels please see ucs_thread_mode_t.

◆ ucp_context_attr

struct ucp_context_attr

The structure defines the attributes that characterize the particular context.

Data Fields
uint64_t field_mask

Mask of valid fields in this structure, using bits from ucp_context_attr_field. Fields not specified in this mask will be ignored. Provides ABI compatibility with respect to adding new fields.

size_t request_size

Size of UCP non-blocking request. When pre-allocated request is used (e.g. in ucp_tag_recv_nbr) it should have enough space to fit UCP request data, which is defined by this value.

ucs_thread_mode_t thread_mode

Thread safe level of the context. For supported thread levels please see ucs_thread_mode_t.

uint64_t memory_types

Mask of which memory types are supported, for supported memory types please see ucs_memory_type_t.

char name[UCP_ENTITY_NAME_MAX]

Tracing and analysis tools can use name to identify this UCX context.

◆ ucp_tag_recv_info

struct ucp_tag_recv_info

The UCP receive information descriptor is allocated by application and filled in with the information about the received message by ucp_tag_probe_nb or ucp_tag_recv_request_test routines or ucp_tag_recv_callback_t callback argument.

Examples
ucp_client_server.c, and ucp_hello_world.c.
Data Fields
ucp_tag_t sender_tag

Sender tag

size_t length

The size of the received data

◆ ucp_request_param_t

struct ucp_request_param_t

The structure ucp_request_param_t is used to specify datatype of operation, provide user request in case the external request is used, set completion callback and custom user data passed to this callback.

Example: implementation of function to send contiguous buffer to ep and invoke callback function at operation completion. If the operation completed immediately (status == UCS_OK) then callback is not called.

ucs_status_ptr_t send_data(ucp_ep_h ep, void *buffer, size_t length,
ucp_tag_t tag, void *request)
{
.request = request,
.cb.send = custom_send_callback_f,
.user_data = pointer_to_user_context_passed_to_cb
};
status = ucp_tag_send_nbx(ep, buffer, length, tag, &param);
if (UCS_PTR_IS_ERR(status)) {
handle_error(status);
} else if (status == UCS_OK) {
// operation is completed
}
return status;
}
uint64_t ucp_tag_t
UCP Tag Identifier.
Definition ucp_def.h:257
ucs_status_ptr_t ucp_tag_send_nbx(ucp_ep_h ep, const void *buffer, size_t count, ucp_tag_t tag, const ucp_request_param_t *param)
Non-blocking tagged-send operation.
@ UCP_OP_ATTR_FIELD_CALLBACK
Definition ucp.h:708
@ UCP_OP_ATTR_FIELD_REQUEST
Definition ucp.h:707
void * request
Definition ucp.h:1758
uint32_t op_attr_mask
Definition ucp.h:1747
Operation parameters passed to ucp_tag_send_nbx, ucp_tag_send_sync_nbx, ucp_tag_recv_nbx,...
Definition ucp.h:1741
struct ucp_ep * ucp_ep_h
UCP Endpoint.
Definition ucp_def.h:92
void * ucs_status_ptr_t
Status pointer.
Definition status.h:106
@ UCS_OK
Definition status.h:47
Examples
ucp_client_server.c, and ucp_hello_world.c.
Data Fields
uint32_t op_attr_mask

Mask of valid fields in this structure and operation flags, using bits from ucp_op_attr_t. Fields not specified in this mask will be ignored. Provides ABI compatibility with respect to adding new fields.

uint32_t flags
void * request

Request handle allocated by the user. There should be at least UCP request size bytes of available space before the request. The size of the UCP request can be obtained by ucp_context_query function.

union ucp_request_param_t.cb cb

Callback function that is invoked whenever the send or receive operation is completed.

ucp_datatype_t datatype

Datatype descriptor for the elements in the buffer. In case the op_attr_mask & UCP_OP_ATTR_FIELD_DATATYPE bit is not set, then use default datatype ucp_dt_make_contig(1)

void * user_data

Pointer to user data passed to callback function.

void * reply_buffer

Reply buffer. Can be used for storing operation result, for example by ucp_atomic_op_nbx.

ucs_memory_type_t memory_type

Memory type of the buffer. see ucs_memory_type_t for possible memory types. An optimization hint to avoid memory type detection for request buffer. If this value is not set (along with its corresponding bit in the op_attr_mask - UCP_OP_ATTR_FIELD_MEMORY_TYPE), then use default UCS_MEMORY_TYPE_UNKNOWN which means the memory type will be detected internally.

union ucp_request_param_t.recv_info recv_info

Pointer to the information where received data details are stored in case of an immediate completion of receive operation. The user has to provide a pointer to valid memory/variable which will be updated on function return.

ucp_mem_h memh

Memory handle for pre-registered buffer. If the handle is provided, protocols that require registered memory can skip the registration step. As a result, the communication request overhead can be reduced and the request can be completed faster. The memory handle should be obtained by calling ucp_mem_map.

◆ ucp_request_param_t.cb

union ucp_request_param_t.cb

Callback function that is invoked whenever the send or receive operation is completed.

Data Fields
ucp_send_nbx_callback_t send
ucp_tag_recv_nbx_callback_t recv
ucp_stream_recv_nbx_callback_t recv_stream
ucp_am_recv_data_nbx_callback_t recv_am

◆ ucp_request_param_t.recv_info

union ucp_request_param_t.recv_info

Pointer to the information where received data details are stored in case of an immediate completion of receive operation. The user has to provide a pointer to valid memory/variable which will be updated on function return.

Data Fields
size_t * length
ucp_tag_recv_info_t * tag_info

Macro Definition Documentation

◆ UCP_ENTITY_NAME_MAX

#define UCP_ENTITY_NAME_MAX   32

Typedef Documentation

◆ ucp_lib_attr_t

typedef struct ucp_lib_attr ucp_lib_attr_t

The structure defines the attributes that characterize the Library.

◆ ucp_context_attr_t

The structure defines the attributes that characterize the particular context.

◆ ucp_tag_recv_info_t

The UCP receive information descriptor is allocated by application and filled in with the information about the received message by ucp_tag_probe_nb or ucp_tag_recv_request_test routines or ucp_tag_recv_callback_t callback argument.

◆ ucp_context_h

typedef struct ucp_context* ucp_context_h

UCP application context (or just a context) is an opaque handle that holds a UCP communication instance's global information. It represents a single UCP communication instance. The communication instance could be an OS process (an application) that uses UCP library. This global information includes communication resources, endpoints, memory, temporary file storage, and other communication information directly associated with a specific UCP instance. The context also acts as an isolation mechanism, allowing resources associated with the context to manage multiple concurrent communication instances. For example, users using both MPI and OpenSHMEM sessions simultaneously can isolate their communication by allocating and using separate contexts for each of them. Alternatively, users can share the communication resources (memory, network resource context, etc.) between them by using the same application context. A message sent or a RMA operation performed in one application context cannot be received in any other application context.

◆ ucp_request_init_callback_t

typedef void(* ucp_request_init_callback_t) (void *request)

This callback routine is responsible for the request initialization.

Parameters
[in]requestRequest handle to initialize.

◆ ucp_request_cleanup_callback_t

typedef void(* ucp_request_cleanup_callback_t) (void *request)

This callback routine is responsible for cleanup of the memory associated with the request.

Parameters
[in]requestRequest handle to cleanup.

Enumeration Type Documentation

◆ ucp_params_field

The enumeration allows specifying which fields in ucp_params_t are present. It is used to enable backward compatibility support.

Enumerator
UCP_PARAM_FIELD_FEATURES 

features

UCP_PARAM_FIELD_REQUEST_SIZE 

request_size

UCP_PARAM_FIELD_REQUEST_INIT 

request_init

UCP_PARAM_FIELD_REQUEST_CLEANUP 

request_cleanup

UCP_PARAM_FIELD_TAG_SENDER_MASK 

tag_sender_mask

UCP_PARAM_FIELD_MT_WORKERS_SHARED 

mt_workers_shared

UCP_PARAM_FIELD_ESTIMATED_NUM_EPS 

estimated_num_eps

UCP_PARAM_FIELD_ESTIMATED_NUM_PPN 

estimated_num_ppn

UCP_PARAM_FIELD_NAME 

name

◆ ucp_feature

The enumeration list describes the features supported by UCP. An application can request the features using UCP parameters during UCP initialization process.

Enumerator
UCP_FEATURE_TAG 

Request tag matching support

UCP_FEATURE_RMA 

Request remote memory access support

UCP_FEATURE_AMO32 

Request 32-bit atomic operations support

UCP_FEATURE_AMO64 

Request 64-bit atomic operations support

UCP_FEATURE_WAKEUP 

Request interrupt notification support

UCP_FEATURE_STREAM 

Request stream support

UCP_FEATURE_AM 

Request Active Message support

UCP_FEATURE_EXPORTED_MEMH 

Request support mapping a peer's memory handle that was created by ucp_mem_map and packed by ucp_memh_pack with the flag UCP_MEMH_PACK_FLAG_EXPORT and use it for local operations

◆ ucp_lib_attr_field

The enumeration allows specifying which fields in ucp_lib_attr_t are present. It is used to enable backward compatibility support.

Enumerator
UCP_LIB_ATTR_FIELD_MAX_THREAD_LEVEL 

UCP library maximum supported thread level flag

◆ ucp_context_attr_field

The enumeration allows specifying which fields in ucp_context_attr_t are present. It is used to enable backward compatibility support.

Enumerator
UCP_ATTR_FIELD_REQUEST_SIZE 

UCP request size

UCP_ATTR_FIELD_THREAD_MODE 

UCP context thread flag

UCP_ATTR_FIELD_MEMORY_TYPES 

UCP supported memory types

UCP_ATTR_FIELD_NAME 

UCP context name

Function Documentation

◆ ucp_lib_query()

ucs_status_t ucp_lib_query ( ucp_lib_attr_t attr)

This routine fetches information about the UCP library attributes.

Parameters
[out]attrFilled with attributes of the UCP library.
Returns
Error code as defined by ucs_status_t

◆ ucp_get_version()

void ucp_get_version ( unsigned *  major_version,
unsigned *  minor_version,
unsigned *  release_number 
)

This routine returns the UCP library version.

Parameters
[out]major_versionFilled with library major version.
[out]minor_versionFilled with library minor version.
[out]release_numberFilled with library release number.

◆ ucp_get_version_string()

const char * ucp_get_version_string ( void  )

This routine returns the UCP library version as a string which consists of: "major.minor.release".

◆ ucp_init()

static ucs_status_t ucp_init ( const ucp_params_t params,
const ucp_config_t config,
ucp_context_h context_p 
)
inlinestatic

This routine creates and initializes a UCP application context.

Warning
This routine must be called before any other UCP function call in the application.

This routine checks API version compatibility, then discovers the available network interfaces, and initializes the network resources required for discovering of the network and memory related devices. This routine is responsible for initialization all information required for a particular application scope, for example, MPI application, OpenSHMEM application, etc.

Note
  • Higher level protocols can add additional communication isolation, as MPI does with its communicator object. A single communication context may be used to support multiple MPI communicators.
  • The context can be used to isolate the communication that corresponds to different protocols. For example, if MPI and OpenSHMEM are using UCP to isolate the MPI communication from the OpenSHMEM communication, users should use different application context for each of the communication libraries.
Parameters
[in]configUCP configuration descriptor allocated through ucp_config_read() routine.
[in]paramsUser defined ucp_params_t configurations for the UCP application context.
[out]context_pInitialized UCP application context.
Returns
Error code as defined by ucs_status_t
Examples
ucp_client_server.c, and ucp_hello_world.c.

◆ ucp_cleanup()

void ucp_cleanup ( ucp_context_h  context_p)

This routine finalizes and releases the resources associated with a UCP application context.

Warning
An application cannot call any UCP routine once the UCP application context released.

The cleanup process releases and shuts down all resources associated with the application context. After calling this routine, calling any UCP routine without calling UCP initialization routine is invalid.

Parameters
[in]context_pHandle to UCP application context.
Examples
ucp_client_server.c, and ucp_hello_world.c.

◆ ucp_context_query()

ucs_status_t ucp_context_query ( ucp_context_h  context_p,
ucp_context_attr_t attr 
)

This routine fetches information about the context.

Parameters
[in]context_pHandle to UCP application context.
[out]attrFilled with attributes of context_p context.
Returns
Error code as defined by ucs_status_t

◆ ucp_context_print_info()

void ucp_context_print_info ( const ucp_context_h  context,
FILE *  stream 
)

This routine prints information about the context configuration: including memory domains, transport resources, and other useful information associated with the context.

Parameters
[in]contextPrint this context object's configuration.
[in]streamOutput stream on which to print the information.