.. _man3-PMIx_Load_topology:

PMIx_Load_topology
==================

.. include_body

``PMIx_Load_topology`` |mdash| Load the local hardware topology description.


SYNOPSIS
--------

.. code-block:: c

   #include <pmix.h>

   pmix_status_t PMIx_Load_topology(pmix_topology_t *topo);


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

.. code-block:: python3

  from pmix import *

  foo = PMIxClient()
  # ... after a successful foo.init() ...
  rc = foo.load_topology()


INPUT PARAMETERS
----------------

* ``topo``: Pointer to a ``pmix_topology_t`` structure into which the topology
  description of the local node is to be loaded. The structure must be
  initialized by the caller prior to the call (for example, with
  ``PMIx_Topology_construct()``). If a particular topology *source* is required
  (e.g., ``"hwloc"``), the ``source`` field of the structure must be set to that
  value before the call; otherwise the library selects an available source.


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

Obtain the topology description of the local node and load it into the provided
``pmix_topology_t`` structure. This is a blocking operation that returns once the
topology has been loaded.

If the ``source`` field of the provided ``pmix_topology_t`` is set, the PMIx
library must return a description from the specified implementation or else
indicate that the implementation is not available by returning
``PMIX_ERR_NOT_SUPPORTED``.

The returned description should be treated as a read-only object; attempts to
modify it may result in errors. The PMIx library is responsible for performing
any required cleanup of the returned topology when the client library finalizes.

Ownership of the ``source`` field depends on who set it:

* If the caller set the ``source`` field before the call to request a
  particular implementation, that string belongs to the caller, and the caller
  remains responsible for releasing it.
* If the caller did *not* set the ``source`` field, the library fills it in on
  return with a read-only, statically allocated string identifying the source
  of the returned topology. The caller must **not** modify or release this
  string; the library manages its lifetime.

In neither case should the caller destruct or free the returned topology
itself (for example with ``PMIx_Topology_destruct()``): the topology object is
shared, library-managed state, and releasing it would corrupt the library's
internal copy. The library performs the necessary cleanup at finalize.


RETURN VALUE
------------

Returns ``PMIX_SUCCESS`` when a valid topology description has been loaded. 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.
* ``PMIX_ERR_NOT_AVAILABLE`` |mdash| the operation cannot be serviced because the
  library's progress engine has been stopped.
* ``PMIX_ERR_NOT_FOUND`` |mdash| the requested topology could not be found.
* ``PMIX_ERR_NOT_SUPPORTED`` |mdash| the requested source is not available in the
  current implementation.

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


NOTES
-----

It is the responsibility of the caller to ensure that the ``topo`` argument is
properly initialized prior to calling this API. If no ``source`` was specified,
the caller should inspect the returned ``source`` field to verify that the
returned topology description is compatible with the caller's code.


.. seealso::
   :ref:`PMIx_Init(3) <man3-PMIx_Init>`,
   :ref:`PMIx_Compute_distances(3) <man3-PMIx_Compute_distances>`,
   :ref:`pmix_status_t(5) <man5-pmix_status_t>`,
   :ref:`pmix_topology_t(5) <man5-pmix_topology_t>`
