UCX  1.8
Unified Communication X

Data Structures

struct  ucp_context_attr
 Context attributes. More...
 
struct  ucp_tag_recv_info
 UCP receive information descriptor. More...
 

Typedefs

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

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 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 configuration features. More...
 
enum  ucp_context_attr_field { UCP_ATTR_FIELD_REQUEST_SIZE = UCS_BIT(0), UCP_ATTR_FIELD_THREAD_MODE = UCS_BIT(1) }
 UCP context attributes field mask. More...
 

Functions

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

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_context_attr

struct ucp_context_attr

The structure defines the attributes which 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.

◆ 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_hello_world.c.
Data Fields
ucp_tag_t sender_tag

Sender tag

size_t length

The size of the received data

Typedef Documentation

◆ ucp_context_attr_t

The structure defines the attributes which 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_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_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

Function Documentation

◆ 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 it's 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_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_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.