UCX  1.8
Unified Communication X
Data Structures | Typedefs | Functions
UCP Configuration
Unified Communication Protocol (UCP) API

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

◆ ucp_params

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 will 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

size_t estimated_num_ppn

An optimization hint for a single node. For example, when used from MPI or OpenSHMEM libraries, this number will specify the number of Processes Per Node (PPN) in the job. Does not affect semantics, only transport selection criteria and the resulting performance. The value can be also set by the UCX_NUM_PPN environment variable, which will override the number of endpoints set by estimated_num_ppn

Typedef Documentation

◆ ucp_params_t

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.

◆ ucp_config_t

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

◆ ucp_config_read()

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_prefixIf 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]filenameIf 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_pPointer to configuration descriptor as defined by ucp_config_t.
Returns
Error code as defined by ucs_status_t
Examples
ucp_hello_world.c.

◆ ucp_config_release()

void ucp_config_release ( ucp_config_t *  config)

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

Parameters
[out]configConfiguration descriptor as defined by ucp_config_t.
Examples
ucp_hello_world.c.

◆ ucp_config_modify()

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]configConfiguration to modify.
[in]nameConfiguration variable name.
[in]valueValue to set.
Returns
Error code.

◆ ucp_config_print()

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]configConfiguration descriptor to print.
[in]streamOutput stream to print the configuration to.
[in]titleConfiguration title to print.
[in]print_flagsFlags that control various printing options.
Examples
ucp_hello_world.c.