.. _man3-PMIx_Get_relative_locality:

PMIx_Get_relative_locality
==========================

.. include_body

``PMIx_Get_relative_locality`` |mdash| Get the relative locality of two local
processes given their locality strings.


SYNOPSIS
--------

.. code-block:: c

   #include <pmix.h>

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


Python Syntax
^^^^^^^^^^^^^

.. code-block:: python3

  from pmix import *

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


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.


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.


DESCRIPTION
-----------

Parse the locality strings of two processes (as returned by
:ref:`PMIx_Get(3) <man3-PMIx_Get>` 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) |mdash| locality could not be determined.
* ``PMIX_LOCALITY_NONLOCAL`` (0x8000) |mdash| the processes share nothing (are
  not on the same node).
* ``PMIX_LOCALITY_SHARE_HWTHREAD`` (0x0001) |mdash| share a hardware thread.
* ``PMIX_LOCALITY_SHARE_CORE`` (0x0002) |mdash| share a core.
* ``PMIX_LOCALITY_SHARE_L1CACHE`` (0x0004) |mdash| share an L1 cache.
* ``PMIX_LOCALITY_SHARE_L2CACHE`` (0x0008) |mdash| share an L2 cache.
* ``PMIX_LOCALITY_SHARE_L3CACHE`` (0x0010) |mdash| share an L3 cache.
* ``PMIX_LOCALITY_SHARE_PACKAGE`` (0x0020) |mdash| share a package.
* ``PMIX_LOCALITY_SHARE_NUMA`` (0x0040) |mdash| share a NUMA domain.
* ``PMIX_LOCALITY_SHARE_NODE`` (0x4000) |mdash| reside on the same node.


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`` |mdash| 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``.


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 :ref:`pmix_info_t(5) <man5-pmix_info_t>` directives. This is an intentional
exception: the operation is a purely local comparison of two strings and takes
no attributes.


.. seealso::
   :ref:`PMIx_Get(3) <man3-PMIx_Get>`,
   :ref:`PMIx_Get_cpuset(3) <man3-PMIx_Get_cpuset>`,
   :ref:`PMIx_Parse_cpuset_string(3) <man3-PMIx_Parse_cpuset_string>`,
   :ref:`PMIx_Compute_distances(3) <man3-PMIx_Compute_distances>`,
   :ref:`PMIx_Load_topology(3) <man3-PMIx_Load_topology>`,
   :ref:`pmix_status_t(5) <man5-pmix_status_t>`,
   :ref:`pmix_locality_t(5) <man5-pmix_locality_t>`