.. _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_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) `, :ref:`PMIx_Compute_distances(3) `, :ref:`pmix_status_t(5) `, :ref:`pmix_topology_t(5) `