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

typedef struct ucp_context_attr ucp_context_attr_t

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

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

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ ucp_context_attr

◆ ucp_tag_recv_info

Typedef Documentation

◆ ucp_context_attr_t

◆ ucp_tag_recv_info_t

◆ ucp_context_h

◆ ucp_request_init_callback_t

◆ ucp_request_cleanup_callback_t

Enumeration Type Documentation

◆ ucp_params_field

◆ ucp_feature

◆ ucp_context_attr_field

Function Documentation

◆ ucp_get_version()

◆ ucp_get_version_string()

◆ ucp_init()

◆ ucp_cleanup()

◆ ucp_context_query()

◆ ucp_context_print_info()