UCP Configuration

Data Structures
struct	ucp_params
	Tuning parameters for UCP library. More...

Typedefs
typedef struct ucp_params	ucp_params_t
	Tuning parameters for UCP library. More...
typedef struct ucp_config	ucp_config_t
	UCP configuration descriptor. More...

Functions
ucs_status_t	ucp_config_read (const char *env_prefix, const char *filename, ucp_config_t **config_p)
	Read UCP configuration descriptor. More...
void	ucp_config_release (ucp_config_t *config)
	Release configuration descriptor. More...
ucs_status_t	ucp_config_modify (ucp_config_t *config, const char *name, const char *value)
	Modify context configuration. More...
void	ucp_config_print (const ucp_config_t *config, FILE *stream, const char *title, ucs_config_print_flags_t print_flags)
	Print configuration information. More...

Detailed Description

This section describes routines for configuration of the UCP network layer

---

Data Structure Documentation

struct ucp_params

The structure defines the parameters that are used for UCP library tuning during UCP library initialization.

Note

UCP library implementation uses the features parameter to optimize the library functionality that minimize memory footprint. For example, if the application does not require send/receive semantics UCP library may avoid allocation of expensive resources associated with send/receive queues.

Examples:

ucp_hello_world.c.

Data Fields
uint64_t	field_mask	Mask of valid fields in this structure, using bits from ucp_params_field. Fields not specified in this mask will be ignored. Provides ABI compatibility with respect to adding new fields.
uint64_t	features	UCP features that are used for library initialization. It is recommended for applications only to request the features that are required for an optimal functionality This field must be specified.
size_t	request_size	The size of a reserved space in a non-blocking requests. Typically applications use this space for caching own structures in order to avoid costly memory allocations, pointer dereferences, and cache misses. For example, MPI implementation can use this memory for caching MPI descriptors This field defaults to 0 if not specified.
ucp_request_init_callback_t	request_init	Pointer to a routine that is used for the request initialization. This function will be called only on the very first time a request memory is initialized, and may not be called again if a request is reused. If a request should be reset before the next reuse, it can be done before calling ucp_request_free. NULL can be used if no such is function required, which is also the default if this field is not specified by field_mask.
ucp_request_cleanup_callback_t	request_cleanup	Pointer to a routine that is responsible for final cleanup of the memory associated with the request. This routine may not be called every time a request is released. For some implementations, the cleanup call may be delayed and only invoked at ucp_worker_destroy. NULL can be used if no such function is required, which is also the default if this field is not specified by field_mask.
uint64_t	tag_sender_mask	Mask which specifies particular bits of the tag which can uniquely identify the sender (UCP endpoint) in tagged operations. This field defaults to 0 if not specified.
int	mt_workers_shared	This flag indicates if this context is shared by multiple workers from different threads. If so, this context needs thread safety support; otherwise, the context does not need to provide thread safety. For example, if the context is used by single worker, and that worker is shared by multiple threads, this context does not need thread safety; if the context is used by worker 1 and worker 2, and worker 1 is used by thread 1 and worker 2 is used by thread 2, then this context needs thread safety. Note that actual thread mode may be different from mode passed to ucp_init. To get actual thread mode use ucp_context_query.
size_t	estimated_num_eps	An optimization hint of how many endpoints will be created on this context. For example, when used from MPI or SHMEM libraries, this number would specify the number of ranks (or processing elements) in the job. Does not affect semantics, but only transport selection criteria and the resulting performance. The value can be also set by UCX_NUM_EPS environment variable. In such case it will override the number of endpoints set by estimated_num_eps

Typedef Documentation

typedef struct ucp_params ucp_params_t

The structure defines the parameters that are used for UCP library tuning during UCP library initialization.

Note

UCP library implementation uses the features parameter to optimize the library functionality that minimize memory footprint. For example, if the application does not require send/receive semantics UCP library may avoid allocation of expensive resources associated with send/receive queues.

typedef struct ucp_config ucp_config_t

This descriptor defines the configuration for UCP application context. The configuration is loaded from the run-time environment (using configuration files of environment variables) using ucp_config_read routine and can be printed using ucp_config_print routine. In addition, application is responsible to release the descriptor using ucp_config_release routine.

Function Documentation

ucs_status_t ucp_config_read	(	const char *	env_prefix,
		const char *	filename,
		ucp_config_t **	config_p
	)

The routine fetches the information about UCP library configuration from the run-time environment. Then, the fetched descriptor is used for UCP library initialization. The Application can print out the descriptor using print routine. In addition the application is responsible for releasing the descriptor back to the UCP library.

Parameters

[in]	env_prefix	If non-NULL, the routine searches for the environment variables that start with UCX_<env_prefix>_ prefix. Otherwise, the routine searches for the environment variables that start with UCX_ prefix.
[in]	filename	If non-NULL, read configuration from the file defined by filename. If the file does not exist, it will be ignored and no error reported to the application.
[out]	config_p	Pointer to configuration descriptor as defined by ucp_config_t.

Returns

Error code as defined by ucs_status_t

Examples:

ucp_hello_world.c.

void ucp_config_release

(

ucp_config_t *

config

)

The routine releases the configuration descriptor that was allocated through ucp_config_read() routine.

Parameters

[out]

config

Configuration descriptor as defined by ucp_config_t.

Examples:

ucp_hello_world.c.

ucs_status_t ucp_config_modify	(	ucp_config_t *	config,
		const char *	name,
		const char *	value
	)

The routine changes one configuration setting stored in configuration descriptor.

Parameters

[in]	config	Configuration to modify.
[in]	name	Configuration variable name.
[in]	value	Value to set.

Returns

Error code.

void ucp_config_print	(	const ucp_config_t *	config,
		FILE *	stream,
		const char *	title,
		ucs_config_print_flags_t	print_flags
	)

The routine prints the configuration information that is stored in configuration descriptor.

Parameters

[in]	config	Configuration descriptor to print.
[in]	stream	Output stream to print the configuration to.
[in]	title	Configuration title to print.
[in]	print_flags	Flags that control various printing options.

Examples:

ucp_hello_world.c.