UCP Application Context

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)
{
    ucp_request_param_t param = {
        .op_attr_mask               = UCP_OP_ATTR_FIELD_CALLBACK |
                                      UCP_OP_ATTR_FIELD_REQUEST,
        .request                    = request,
        .cb.send                    = custom_send_callback_f,
        .user_data                  = pointer_to_user_context_passed_to_cb
    };
 
    ucs_status_ptr_t status;
 
    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;
}

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

typedef struct ucp_context_attr ucp_context_attr_t

The structure defines the attributes that characterize the particular context.

ucp_tag_recv_info_t

typedef struct ucp_tag_recv_info 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]

request

Request 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]

request

Request handle to cleanup.

Enumeration Type Documentation

ucp_params_field

enum 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

enum 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

enum 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

enum 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]

attr

Filled 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_version	Filled with library major version.
[out]	minor_version	Filled with library minor version.
[out]	release_number	Filled 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]	config	UCP configuration descriptor allocated through ucp_config_read() routine.
[in]	params	User defined ucp_params_t configurations for the UCP application context.
[out]	context_p	Initialized 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_p

Handle 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_p	Handle to UCP application context.
[out]	attr	Filled 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]	context	Print this context object's configuration.
[in]	stream	Output stream on which to print the information.