18.2.42. PMIx_Get_relative_locality

PMIx_Get_relative_locality — Get the relative locality of two local processes given their locality strings.

18.2.42.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Get_relative_locality(const char *locality1,
                                         const char *locality2,
                                         pmix_locality_t *locality);

18.2.42.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
rc, locality = foo.get_relative_locality(locstr1, locstr2)

18.2.42.2. INPUT PARAMETERS

locality1: Locality string associated with the first process, as obtained from the PMIX_LOCALITY_STRING key.
locality2: Locality string associated with the second process, as obtained from the PMIX_LOCALITY_STRING key.

18.2.42.3. OUTPUT PARAMETERS

locality: Pointer to a pmix_locality_t where the relative locality bitmask is to be constructed. On success it is set to the bitwise-OR of the topology levels the two processes share.

18.2.42.4. DESCRIPTION

Parse the locality strings of two processes (as returned by PMIx_Get(3) using the PMIX_LOCALITY_STRING key) and set the appropriate pmix_locality_t bits in the provided memory location, describing the topology levels the two processes have in common.

Both locality strings must have been generated by the same source (e.g., "hwloc") for the comparison to be meaningful. The returned bitmask is a combination of the following bit values:

PMIX_LOCALITY_UNKNOWN (0x0000) — locality could not be determined.
PMIX_LOCALITY_NONLOCAL (0x8000) — the processes share nothing (are not on the same node).
PMIX_LOCALITY_SHARE_HWTHREAD (0x0001) — share a hardware thread.
PMIX_LOCALITY_SHARE_CORE (0x0002) — share a core.
PMIX_LOCALITY_SHARE_L1CACHE (0x0004) — share an L1 cache.
PMIX_LOCALITY_SHARE_L2CACHE (0x0008) — share an L2 cache.
PMIX_LOCALITY_SHARE_L3CACHE (0x0010) — share an L3 cache.
PMIX_LOCALITY_SHARE_PACKAGE (0x0020) — share a package.
PMIX_LOCALITY_SHARE_NUMA (0x0040) — share a NUMA domain.
PMIX_LOCALITY_SHARE_NODE (0x4000) — reside on the same node.

18.2.42.5. RETURN VALUE

Returns PMIX_SUCCESS on success, with the relative locality bitmask loaded into locality. On error, a negative value corresponding to a PMIx error constant is returned, including:

PMIX_ERR_INIT — the PMIx library has not been initialized.

Any other negative value indicates an appropriate error condition. PMIx error constants are defined in pmix_common.h.

18.2.42.6. NOTES

This API operates only on locality strings that describe two processes on the same node; it is used to determine how “close” the processes are within the node topology.

Unlike most PMIx APIs, PMIx_Get_relative_locality does not accept an array of pmix_info_t(5) directives. This is an intentional exception: the operation is a purely local comparison of two strings and takes no attributes.